⛴️ chore: Bring Canary Up to Date With Dev

This commit is contained in:
Lia 2026-09-28 17:31:04 +00:00
commit ffa54e0259
31 changed files with 1085 additions and 537 deletions

133
AGENTS.md
View file

@ -1,4 +1,9 @@
See CLAUDE.md.
# LibreChat contributor and agent guidance
`AGENTS.md` is the repository's contributor guidance. Backend code lives in `packages/api`
(TypeScript) and `packages/data-schemas` (database methods); `api` is legacy Express wiring.
Shared API types and services live in `packages/data-provider`, and the React app lives in
`client` with shared primitives in `packages/client`.
## Branching and pull requests
@ -18,8 +23,9 @@ explicitly based on `canary` stays there; the main-to-dev retarget workflow does
Still link related issues in the PR (for example, `Related to #N`) so the work remains
traceable. `Fixes #N` does not close an issue on a `dev` or `canary` merge — GitHub honors closing
keywords only on the default branch. Close resolved issues by hand after merging. Worktrees share
one stash stack, so never use a bare `git stash pop`. See the detailed policy in `CLAUDE.md` under
"Branching and Pull Requests".
one stash stack, so never use a bare `git stash pop`. Prefer a WIP commit; if a stash is necessary,
apply the specific tagged entry. The `target: main` label and release-bound upstream branches are
exempt from the main-to-dev retarget workflow; do not use either to backport ordinary work.
Write the description for a reader who has not followed the branch: what breaks, what triggers it,
how it behaves after the change, then one or two views of the mechanism — a focused diff, a call
@ -34,17 +40,18 @@ Read the inline review threads themselves — a summary comment or notification
Audit each one against the current code, fix what is valid, and reject what is obsolete in a reply
that says why. After each round: focused tests, `npx tsc --noEmit` in every workspace you changed,
push, then request the next review naming the pull request's exact remote head — a clean review of
an earlier head says nothing about what you just pushed, and CI runs on its own clock. After two
actionable rounds, stop patching thread by thread and read the subsystem by invariant instead.
Which reviewer and what phrase triggers it will change; that the review must cover the exact pushed
head will not.
an earlier head says nothing about what you just pushed, and CI runs on its own clock. Reply on
each resolved thread with the resolving commit and evidence. After two actionable rounds, stop
patching thread by thread and read the subsystem by invariant instead: identity, authorization,
persistence, retry, cancellation, cleanup and mixed-version behavior where relevant. Which reviewer
and what phrase triggers it will change; that the review must cover the exact pushed head will not.
A clean review is one completion signal, not the definition of done. Ship the observable experience
— loading, empty, success, failure, cancellation, retry, restored session — with strings localized,
accessibility intact, defaults and stored data preserved, and no backend capability left without a
frontend entry point. Report the pushed head, what you ran locally, CI state, the review result at
that head, and any finding you rejected with the reasoning. See `CLAUDE.md` under "Review and
Completion".
frontend entry point. Keep fixes small and test the missed behavior. Report the pushed head, what you
ran locally, CI state, the review result at that head, any finding you rejected with the reasoning,
and checks you could not run.
## Verification
@ -56,11 +63,17 @@ See [budgets, reproduction and failure diagnosis](e2e/lighthouse/README.md).
A green build is not a typecheck: `packages/api`, `packages/client` and `packages/data-schemas` build
with `tsdown`, which emits without checking types. Run `npx tsc --noEmit` in the workspace you
changed. `packages/client` excludes `*.spec.ts(x)` and `*.test.ts(x)` from typechecking entirely.
`npm run sort-imports` with no arguments rewrites every source root — pass the paths you touched. See
`CLAUDE.md` under "Typechecking" and "Formatting".
`npm run sort-imports` with no arguments rewrites every source root — pass the paths you touched.
Run `npm run static-checks -- --against origin/dev` to reproduce the PR's static checks; use
`npm run static-checks:full` for the slower gates. Fix all formatting, lint, and TypeScript
warnings/errors in the code you change.
## Module boundaries and configuration
All new backend behavior belongs in TypeScript under `packages/api`; database-specific shared logic
belongs in `packages/data-schemas`, and frontend/backend shared API logic belongs in
`packages/data-provider`. Build data-provider from the project root with `npm run build:data-provider`.
`/api` holds wiring, not behavior. When a change would add logic to a CJS file there — a branch, a
helper, a validation step, a service call — the logic belongs in `packages/api`, and the JS file
keeps requires, route registration and the call into the TS module (`MCPRequestContext.js` is the
@ -85,7 +98,46 @@ supplies, so a second implementation is a new argument instead of a new branch.
under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy. This is the
backend half of client state ownership: pass it in, do not reach for it.
See `CLAUDE.md` under "Workspace Boundaries".
## Service failures and user-facing errors
This section applies to backend services (`packages/api`) and database methods/repositories
(`packages/data-schemas`), not to React components. For new or substantially changed code in
those layers, choose failure behavior at the contract boundary instead of treating every
unsuccessful outcome as an exception:
- Return a plain value on success. Use `null` only for a documented absence (for example, a
successful lookup with no record), never to hide a query failure.
- For an expected failure the caller can handle without aborting the operation, prefer a typed
discriminated result such as `{ ok: true; value: T } | { ok: false; error: { code: string;
message?: string } }`. Keep an existing domain-specific result shape when changing it would
break callers; do not introduce interchangeable `ok`, `valid`, and bare `{ message }` contracts
in the same service. Codes should be stable, machine-readable identifiers when the caller
needs to distinguish failures. Internal validation helpers may use the existing local pattern.
- Throw for unexpected operational failures (database, provider, network) and violated invariants.
Use a typed/coded error when a boundary must recognize a particular failure. Catch where you can
recover or translate it; otherwise let it reach the owning request or job boundary. Do not catch
an exception and return a truthy record, `null`, or `{ message }` in its place: callers can then
mistake an outage for data or send it as an HTTP 200. Keep separate migrations for existing
contracts, with their callers and tests, rather than changing wire shapes incidentally.
- At the HTTP, stream, or job boundary, map failures to the existing status and response contract.
Only expose intentionally approved codes and helpful user-safe information. Error disclosure is
a security boundary: never forward raw exceptions, stacks, query text, credentials, request
bodies, headers, provider payloads, or arbitrary `error.message` to a client or persisted
user-visible status. Sanitize diagnostics and log only what the path can safely retain. For
errors that may echo submitted content, prefer `getSafeErrorMetadata` over error text;
`packages/api/src/utils/errors.ts` documents when redacted error text is appropriate.
- Localization is a UI responsibility, not a database-method return shape. When a failure reaches
a user-facing surface, expose a safe, stable code the UI can map to localized, actionable copy
and a fallback. See `client/src/components/Messages/Content/Error/registry.ts` and
`client/src/components/Chat/Trace/Viewer.tsx`. Keep any intentionally disclosed provider detail
behind its existing protection policy rather than treating arbitrary upstream text as safe.
Examples of local contracts, not a mandate to copy their shapes: `packages/api/src/admin/auditLog.ts`
uses a parsing result, `packages/api/src/agents/openai/service.ts` validates before mapping to an
OpenAI-compatible response, and `packages/api/src/skills/sync/errors.ts` names a sync failure by
stable code. `packages/data-schemas/src/methods/prompt.ts` currently returns `{ message }` on query
failure; do not extend that pattern. Test absence versus failure, the boundary's non-success response,
and that sensitive diagnostics cannot reach a user-visible surface.
## Frontend theming and styling
@ -93,22 +145,16 @@ For frontend work, compose existing `@librechat/client` primitives and variants
feature-local styles. Use semantic theme/Tailwind roles for color and shared appearance; do not
introduce raw palette utilities, hard-coded colors, or arbitrary theme CSS. If the system cannot
express a reusable design need, deepen the shared primitive or versioned theme-token registry
instead of copying classes into a feature. Keep genuine layout and behavior local, and document
why any new custom CSS cannot be expressed by the shared system.
`npm run lint` enforces this: `@shadcn/lint` reads each primitive's `cva` variants and reports a
`className` that overrides what the primitive owns, naming the variant, size or file to use
instead. Do not reach for `eslint-disable`, and do not widen a file's recorded count in
`eslint-suppressions.json` to land a restyle — that file holds the backlog the rules inherited, so
raising an entry is a reviewable claim that the override is right. After fixing violations, run
`npm run lint:design:prune`; after moving a file that carries suppressions, run
`npm run lint:design:suppress`. See the detailed policy in `CLAUDE.md` under “Theming and styling.”
instead of copying classes into a feature. Theme definitions select semantic colors and appearance,
not selectors, app behavior, or alternate layouts. Keep genuine layout and behavior local, and
explain why any new custom CSS cannot use shared primitives. Support light/dark and reduced motion;
preserve defaults and test a deliberately different reference theme for reusable new variants.
## Backend auth cache
When adding or changing code that mutates user documents, invalidate the auth user document cache
for affected users, including bulk role and user mutations. See the detailed policy in `CLAUDE.md`
under “Auth cache invalidation”.
for affected users, including bulk role and user mutations. Otherwise burst-cached JWT requests can
serve a stale `req.user` until the cache expires.
## Client state ownership
@ -122,5 +168,38 @@ and keep it inside the feature; app-global preferences and shell state a feature
through props or a small host-supplied context rather than reached for through `~/store`; when a
consumer sits outside the feature you are changing, leave that atom on Recoil and pass it in. Passing
them in is what lets a feature move to its own workspace later without a rewrite, and it keeps the
Jotai conversion scoped to the state a feature owns. See the detailed policy in `CLAUDE.md` under
“Client State Ownership”.
Jotai conversion scoped to the state a feature owns. For persisted atoms, use the helpers in
`client/src/store/jotai-utils.ts`.
## Code style and performance
Use short, single-word file names when possible; group related modules in a single-word directory.
Prefer flat early returns, pure functions, and explicit types. Avoid `any`, broad `unknown`/casts,
duplicated types, and dynamic imports. Extract genuinely repeated logic instead of copying it;
write comments only for non-obvious behavior or public API contracts.
Imports have three sections: package values (shortest line first, with `react` first), `import type`
(longest line first, package types before local types), and local/project values (longest line first).
Use standalone `import type { ... }`, not inline `type` within a value import. Run the scoped
import sorter on files you change.
Avoid extra passes over shared message arrays and unnecessary allocations. For startup and
request paths, reuse already-loaded user/config data, avoid serial database reads, and start
independent reads in parallel. Do not weaken authorization or tenant checks or write a response
before those checks succeed.
## Frontend rules
Use `useLocalize()` for all visible copy and update only English keys in
`client/src/locales/en/translation.json`. Use semantic HTML, keyboard behavior, and ARIA labels.
Use React Query for API interactions and invalidate related queries after mutations; define query
and mutation keys in `packages/data-provider/src/keys.ts`. Put shared endpoint definitions, types,
and data services in `packages/data-provider`, and encode dynamic URL parameters. Cover loading,
success, and failure states in focused component tests.
## Testing
Run focused Jest tests from the owning workspace, not the entire monorepo. Prefer real logic and
spies over mocked internals; use `mongodb-memory-server` for database queries and the real MCP SDK
for MCP behavior. Mock only external HTTP APIs or uncontrollable services. For frontend tests use
the component's colocated `__tests__` and `test/layout-test-utils` where applicable.

469
CLAUDE.md
View file

@ -1,469 +0,0 @@
# LibreChat
## Project Overview
LibreChat is a monorepo with the following key workspaces:
| Workspace | Language | Side | Dependency | Purpose |
|---|---|---|---|---|
| `/api` | JS (legacy) | Backend | `packages/api`, `packages/data-schemas`, `packages/data-provider`, `@librechat/agents` | Express server — minimize changes here |
| `/packages/api` | **TypeScript** | Backend | `packages/data-schemas`, `packages/data-provider` | New backend code lives here (TS only, consumed by `/api`) |
| `/packages/data-schemas` | TypeScript | Backend | `packages/data-provider` | Database models/schemas, shareable across backend projects |
| `/packages/data-provider` | TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend |
| `/client` | TypeScript/React | Frontend | `packages/data-provider`, `packages/client` | Frontend SPA |
| `/packages/client` | TypeScript | Frontend | `packages/data-provider` | Shared frontend utilities |
The source code for `@librechat/agents` (major backend dependency, same team) lives at
<https://github.com/LibreChat-AI/agents>.
---
## Workspace Boundaries
- **All new backend code must be TypeScript** in `/packages/api`.
- **`/api` holds wiring, not behavior.** When a change would add logic to a CJS file under `/api` —
a branch, a helper, a validation step, a new service call — that logic goes in `/packages/api`,
and the JS file keeps only what wires it up: requires, route registration, request plumbing, and
the call into the TS module. `api/server/services/MCPRequestContext.js` is the shape, at thirteen
lines of re-export. "Minimum" describes how much behavior `/api` gains, not how small the diff is:
lifting a function into `/packages/api` and calling it is the larger diff and the correct one.
Editing an existing CJS file is the common case and the rule applies there, not only to new files.
- Database-specific shared logic goes in `/packages/data-schemas`.
- Frontend/backend shared API logic (endpoints, types, data-service) goes in `/packages/data-provider`.
- Build data-provider from project root: `npm run build:data-provider`.
- **Database contracts stay inside `/packages/data-schemas`.** A Mongoose type in an exported
signature — `FilterQuery`, `Types.ObjectId`, `Document`, `HydratedDocument` — makes the storage
engine part of that module's public API, and every consumer then depends on Mongo instead of on
the data it needs. Take and return plain typed objects, and express the query behind a
data-schemas method. The boundary already leaks across dozens of files in `/packages/api`, so the
rule is to stop widening it rather than to rewrite what exists; `/client` carries none of it and
must stay that way.
- **New levers ship configurable.** A limit, timeout, toggle or capability introduced in code earns
a field on `configSchema` (`packages/data-provider/src/config.ts`) so an operator can set it in
`librechat.yaml`, with a default that reproduces today's behavior. Hard-coded constants and
env-only switches need a reason. The schema is also what keeps one definition of the value instead
of a constant, a fallback and a doc line that drift apart.
- **A backend module takes its dependencies, it does not reach for them.** Code in `/packages/api`
should receive its config, database methods and clients from the caller the way
`createModels(mongoose)` receives the app's connection, rather than importing app singletons or
reading global state. A module the caller constructs can be tested without a running app and moved
to another workspace without a rewrite; one that calls `getInstance()` can do neither. This is the
backend half of "Client State Ownership" — pass it in, do not reach for it. The static singletons
under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy.
- **Integrations arrive through an interface the caller supplies.** A provider SDK, storage backend,
vector store or OAuth server is injected, so a second implementation is a new argument instead of
a new branch in shared code, and a test can exercise the real logic against a substitute at the
boundary rather than mocking the module that holds it.
---
## Branching and Pull Requests
- **Normally branch off `dev` and target `dev`.** This is the default for work ready to follow the
regular release path. A maintainer-directed canary exception is described below.
- **`main` is the released branch.** It is kept as a fast-forward of `dev` and synced as-is, so it
is always an ancestor of `dev` — equal to it right after a sync, behind it otherwise. It never
carries a commit that `dev` does not have.
- **Never open a backport pull request to `main`.** Anything merged to `dev` reaches `main` at the
next sync; a second pull request for the same change is redundant.
- **The repository's default branch is `main`**, so `gh pr create` and the GitHub UI target it
unless told otherwise — pass `--base dev` for normal work or `--base canary` for an explicitly
maintainer-directed canary PR.
- Pull requests opened against `main` are retargeted to `dev` automatically by
`.github/workflows/pr-retarget-dev.yml`. The `target: main` label exempts one, as do release-bound
upstream branches (`dev`, `release/*`, `hotfix/*`). PRs deliberately based on `canary` are not
retargeted, including manual sweeps; the script skips them explicitly. Backport branches are
deliberately not exempt — a backport merged straight to `main` breaks the fast-forward invariant.
- **Canary is an explicit, maintainer-selected integration target, not a path that automatically
flows to `dev` or `main`.** Experimental changes and PRs that are ready to merge following review
but must not enter the next `main` sync can go to `canary`. The maintainer may decide this when
assigning the work or while reviewing an older/stale PR. For a new canary PR, branch from the
current `origin/canary` and set `--base canary`. Never infer that a canary-targeted PR should move
to `dev` just because `dev` is the default; do not copy canary features into `dev` without an
explicit maintainer decision. If a stale PR is reassigned to canary, check the PR's base, diff and
exact reviewed head against current canary before changing its base or proposing a new canary
branch/PR; if a rebase changes the head, verify and review that new head before merging.
- **Link related issues in the PR even when they will not auto-close.** Reference each relevant
issue in the description (for example, `Related to #N`) so reviewers can find the context and
track the work. GitHub honors `Fixes #N` and other closing keywords only when a pull request
merges into the default branch (`main`). Merging to `dev` or `canary` does not close an issue,
and the later fast-forward of `main` is not a merge event either — close resolved issues by hand
after merging.
- **Git worktrees share one stash stack.** `refs/stash` lives in the common `.git` directory, so a
bare `git stash pop` in one worktree can take work stashed in another. Prefer a throwaway WIP
commit; if you must stash, `git stash push -m <tag>` and `apply` that specific entry.
- **Write the description for a reader who has not followed the branch.** Say what breaks, what
triggers it, and how it behaves after the change, then show the mechanism with whichever one or
two views make it reviewable — a focused diff, a call tree, a shallow file tree, or a Mermaid
sequence — keeping only the calls, files and state the change actually carries. Describe the code
as it stands: do not narrate what earlier commits tried or what a review round changed. Naming the
merged pull request that caused the bug is different — that is history the reader needs.
`.github/pull_request_template.md` carries the formats and examples.
---
## Review and Completion
### AI review cycles
The reviewer, its trigger phrase and its cadence all change; this subsection is the fluid one, so
rewrite it when they do. What survives a change of tool: a review counts only for the exact commit
it ran on, its findings are judged against the code rather than accepted or dismissed wholesale, and
findings that keep arriving mean the subsystem needs a sweep, not another patch.
- **Inline review threads are the source of truth.** A summary comment, a check name or a
notification list omits findings — read the threads on the pull request itself.
- Audit every finding against the current code. Fix the valid ones; reject the obsolete or wrong
ones in a reply that says why.
- After each round of fixes, run the focused tests and `npx tsc --noEmit` for every workspace you
changed, push, read the pull request's remote head (`gh pr view <n> --json headRefOid`), and
request the next review naming that exact SHA. **A clean review of an earlier head says nothing
about what you just pushed.** Do not wait for CI before asking — review and CI run on their own
clocks.
- Reply on each thread you resolved with the commit that resolved it and the coverage that proves
it.
- **After two actionable rounds** — or sooner, when each fix uncovers an adjacent defect — stop
answering threads one at a time and read the subsystem by invariant: identity, ownership,
authorization, persistence, retry, replay, abort, cleanup, expiry, rollout. Follow producers,
consumers, adapters, alternate write paths, and the final consumer of every limit; check
mixed-version behavior in both directions; read the whole base-to-head diff with the callers and
tests around it; then add transition or failure-injection coverage at the deepest boundary that
owns the behavior.
- The cycle ends when the exact pushed head draws no major findings, or only repeats ones already
resolved. A clean review is one completion signal, not the definition of done.
### Definition of done
- **Ship the observable experience, not the reported path.** Where they apply, cover loading, empty,
success, failure, cancellation, retry and restored-session behavior.
- **A backend capability with no frontend entry point is unfinished**, and so is a control with no
validation, persistence, error handling or authorization behind it.
- Localize every visible string through `useLocalize()`, keep semantic HTML, keyboard behavior and
ARIA intact, and compose shared primitives and semantic theme roles before adding local styling
(see "Frontend Rules"). Custom styling that proves unavoidable still supports light/dark and
reduced motion.
- Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior,
and expose any new lever through `configSchema` rather than a constant (see "Workspace
Boundaries").
- Make the fix the smallest one consistent with the patterns already in the file, and test the
behavior that was missed rather than the line a reviewer pointed at.
- **Report what you actually ran**: the pushed head, the local checks from "Testing" and
"Typechecking", CI state, the review result at that head, and any finding you rejected with the
reasoning. Name the checks you could not run instead of implying coverage.
---
## Code Style
### Naming and File Organization
- **Single-word file names** whenever possible (e.g., `permissions.ts`, `capabilities.ts`, `service.ts`).
- When multiple words are needed, prefer grouping related modules under a **single-word directory** rather than using multi-word file names (e.g., `admin/capabilities.ts` not `adminCapabilities.ts`).
- The directory already provides context — `app/service.ts` not `app/appConfigService.ts`.
### Structure and Clarity
- **Never-nesting**: early returns, flat code, minimal indentation. Break complex operations into well-named helpers.
- **Functional first**: pure functions, immutable data, `map`/`filter`/`reduce` over imperative loops. Only reach for OOP when it clearly improves domain modeling or state encapsulation.
- **No dynamic imports** unless absolutely necessary.
### DRY
- Extract repeated logic into utility functions.
- Reusable hooks / higher-order components for UI patterns.
- Parameterized helpers instead of near-duplicate functions.
- Constants for repeated values; configuration objects over duplicated init code.
- Shared validators, centralized error handling, single source of truth for business rules.
- Shared typing system with interfaces/types extending common base definitions.
- Abstraction layers for external API interactions.
### Iteration and Performance
- **Minimize looping** — especially over shared data structures like message arrays, which are iterated frequently throughout the codebase. Every additional pass adds up at scale.
- Consolidate sequential O(n) operations into a single pass whenever possible; never loop over the same collection twice if the work can be combined.
- Choose data structures that reduce the need to iterate (e.g., `Map`/`Set` for lookups instead of `Array.find`/`Array.includes`).
- Avoid unnecessary object creation; consider space-time tradeoffs.
- Prevent memory leaks: careful with closures, dispose resources/event listeners, no circular references.
### Backend Database Performance
- On request startup and first page load paths, watch for serial database reads.
Multiple round trips to MongoDB can add significant latency when the database
is far from the app server.
- Prefer passing already-loaded request/user/config data through helper
functions instead of re-reading the same user, role, tenant, or principal data.
- When two reads are independent, start them in parallel and gate the response
on the authorization or validation result before returning data.
- Keep authorization, permission, and tenant checks semantically identical when
parallelizing reads. Speculative reads must remain scoped to the authenticated
user or tenant and must not write to the response before validation succeeds.
### Type Safety
- **Never use `any`**. Explicit types for all parameters, return values, and variables.
- **Limit `unknown`** — avoid `unknown`, `Record<string, unknown>`, and `as unknown as T` assertions. A `Record<string, unknown>` almost always signals a missing explicit type definition.
- **Don't duplicate types** — before defining a new type, check whether it already exists in the project (especially `packages/data-provider`). Reuse and extend existing types rather than creating redundant definitions.
- Use union types, generics, and interfaces appropriately.
- All TypeScript and ESLint warnings/errors must be addressed — do not leave unresolved diagnostics.
### Comments and Documentation
- Write self-documenting code; no inline comments narrating what code does.
- JSDoc only for complex/non-obvious logic or intellisense on public APIs.
- Single-line JSDoc for brief docs, multi-line for complex cases.
- Avoid standalone `//` comments unless absolutely necessary.
### Import Order
Imports are organized into three sections:
1. **Package imports** — sorted shortest to longest line length (`react` always first).
2. **`import type` imports** — sorted longest to shortest (package types first, then local types; length resets between sub-groups).
3. **Local/project imports** — sorted longest to shortest.
Multi-line imports count total character length across all lines. Consolidate value imports from the same module. Always use standalone `import type { ... }` — never inline `type` inside value imports.
### JS/TS Loop Preferences
- **Limit looping as much as possible.** Prefer single-pass transformations and avoid re-iterating the same data.
- `for (let i = 0; ...)` for performance-critical or index-dependent operations.
- `for...of` for simple array iteration.
- `for...in` only for object property enumeration.
---
## Frontend Rules (`client/src/**/*`)
### Localization
- All user-facing text must use `useLocalize()`.
- Only update English keys in `client/src/locales/en/translation.json` (other languages are automated externally).
- Semantic key prefixes: `com_ui_`, `com_assistants_`, etc.
### Components
- TypeScript for all React components with proper type imports.
- Semantic HTML with ARIA labels (`role`, `aria-label`) for accessibility.
- Group related components in feature directories (e.g., `SidePanel/Memories/`).
- Use index files for clean exports.
### Theming and styling
- **Compose before styling.** Search `@librechat/client` for an existing primitive, semantic
variant, or composition before adding feature-local classes or CSS.
- **Use semantic roles.** Colors and shared appearance values must come from the semantic
Tailwind/theme roles. Do not add raw palette utilities, hard-coded hex/RGB/HSL colors, or
light/dark-specific values in feature components.
- **Deepen the system when the need is reusable.** Add a focused variant to a shared primitive or
extend the canonical, versioned theme-token registry when multiple screens should share the
same design decision. Do not create shallow local wrappers that merely relocate class strings.
- **Themes are data, not arbitrary CSS.** Theme definitions may select semantic colors and shared
appearance roles. They must not contain selectors, arbitrary CSS, application behavior, or
alternate feature layouts. Preserve existing environment and stored-theme compatibility when
changing the theme engine.
- **Keep layout and behavior local.** Feature structure, responsive layout, state-driven
transitions, and specialized visualization may remain feature-owned. Expose a theme role only
when it represents a stable, reusable appearance decision; do not turn every measurement into a
global token.
- **Treat custom CSS as an exception.** Use it only when shared primitives and semantic utilities
cannot express the requirement. Keep it narrowly scoped, consume theme variables where
applicable, support light/dark and reduced motion, and add a brief code or PR explanation of why
the exception is necessary.
- **Preserve defaults and prove variability.** New theme-aware variants must reproduce the current
default appearance unless a redesign is explicitly requested. Test semantic-token use and, when
extending theme capabilities, include a deliberately different reference theme to prove that
components adapt without feature-specific overrides.
- **The design rules are enforced by `npm run lint`.** `@shadcn/lint` is registered in
`eslint.config.mjs` for `client/src/**` and `packages/client/src/**`. It resolves
`@librechat/client` (and the `~/components/ui` re-exports) as the design system, reads each
primitive's `cva` variants, and reports a `className` that overrides what the primitive owns —
naming the variants, sizes and defining file to use instead. Six rules run at `error`:
`no-restyle` (layout and `icon-*` sizing allowed), `no-raw-colors`, `no-arbitrary-values`
(layout allowed), `no-inline-styles` (measured geometry allowed: width, height, inset,
transform, z-index), `require-static-classes` and `no-unknown-classes`. The last one asks the
installed Tailwind whether a class generates any CSS, which needs v4 and the color tokens in
CSS (`packages/client/src/theme/tokens.css`) for the rule to resolve a theme; under 3.4 its
fallback reported every preset utility (`duration-theme-fast`, `rounded-theme-control`) as a
typo. What it cannot see is a class defined in a stylesheet Tailwind does not read, or one a
dependency puts in the DOM, so those live in its `allow` list in `eslint.config.mjs`, add a
name there when a plain selector or a third party owns it, and fix the class when nothing
defines it. `no-raw-colors` additionally reports a `bg-`/`text-`/`border-` name whose token is
not declared in the theme, which is the same failure wearing a color's clothes.
- **Contracts say what a caller owns; suppressions say what is owed.** A `no-restyle` contract in
`eslint.config.mjs` opens a category for one component because the caller legitimately owns it:
`Label`, `Description`, `DialogTitle` and `DialogDescription` take the caller's typography, and
`Skeleton` takes the silhouette and footprint of the content it stands in for. Color stays with
the theme in every case. Widen a contract when a whole category belongs to callers; do not widen
one to clear a single call site.
- **The existing backlog is recorded, not exempted.** `eslint-suppressions.json` holds the
violations the tree carried when the rules landed, as a per-file, per-rule count.
Adding a violation to a file reports every violation of that rule in it, so raising a file's
count is a visible diff in that file, review it like any other change, and expect a raise to
be justified by what the diff does. Strengthening a rule is the one case where counts rise in
files nobody edited: when a rule starts seeing a class it could not classify before, the
violations it reports are the tree's existing styling, and recording them is the same backlog
arriving later. Say which change did that and keep the two apart in review.
`npm run lint:design:prune` drops entries whose violations are gone (do this after fixing
some); `npm run lint:design:suppress` re-records the design rules and then prunes, which is
what a file move needs, since suppressions are keyed by path, the re-record adds the new
path and only the prune removes the old one. It re-baselines everything under `client/src`
and `packages/client/src`, so for a single move prefer a scoped re-record of just that file:
the same six `--suppress-rule` flags `lint:design:suppress` passes (`shadcn/no-restyle`,
`no-raw-colors`, `no-arbitrary-values`, `no-inline-styles`, `require-static-classes`,
`no-unknown-classes`) with
`<new/path.tsx>` in place of the directories, since a moved file usually carries entries for
more than one rule, followed by `npm run lint:design:prune`;
`npm run lint:design:suppress -- <file>` does not scope, because npm appends the argument to
the script's own directory arguments. Neither command changes which rules run; both only
rewrite the recorded counts. The re-record's own exit status is deliberately ignored: it lints
the roots under every rule, those roots carry a pre-existing error backlog, and the baseline is
written before ESLint reports it — so `lint:design:suppress` runs `lint:design:record` inside
`|| node -e ""` (`true` is not a command under `cmd.exe`, where npm runs scripts on Windows)
and lets the prune be the step that can fail. Expect the same when running a scoped re-record
by hand, and build the primitives first: `shadcn/no-restyle` reads each variant out of
`packages/client/dist`, so a missing or stale bundle records counts that describe a library
nobody is compiling against. `lint`, `lint:fix`, `lint:design:record` and `lint:design:prune`
each run `npm run build:client-package` before they lint, which is why `lint:design:suppress`
no longer builds on its own account; a bare `eslint --suppress-rule ...` does not, so run that
build ahead of it.
- **The ratchet is on the count, and on what the count stands for.** ESLint compares a file's
current violation count for a rule against the recorded one and suppresses when it is not higher,
so replacing one suppressed violation with a different violation of the same rule in the same
file keeps the count equal and ESLint reports nothing. The backlog is a budget per file, but it is
not a budget you may respend: for every file a diff touches, the runner lints that file's version
at the merge base and reports a design-rule message the head has that the base did not, beyond
whatever that entry's count grew by. So a swap arrives as a failure naming the new violation, a
violation that merely moved does not, adding one with the count raised to cover it is the
documented `npm run lint:design:suppress` path and stays green — the raised count is the line a
reviewer reads — and a file the change adds brings no allowance with it, while a renamed one
keeps what its violations came with. Two kinds of swap still pass: one whose diagnostic message
is the same as the message it replaced, because some rules name the property and not the value
(`Inline style sets display.` is one message for `none` and for `flex`), and one caused by the
diff's own change to a primitive or to the config, because both versions are linted under the
head's design inputs. `npm run static-checks` and the Static Checks lane also
validate the baseline itself (shape, positive counts, rules the plugin defines, paths that still
exist, paths a design-rule lint actually reports on, and counts that match the file's violations).
- **The design rules read JSX, not CSS.** They are AST rules over `className`, `cva` and
`style` in `{ts,tsx,js,jsx}`, so a `.css` file under either root — `client/src/style.css`,
`packages/client/src/components/Field.css` — is outside every one of them, and so is the
changed-file runner's selection. A raw hex in a stylesheet is caught by review, not by
`npm run lint`. The theme tokens are the exception: they live in CSS and carry their own
check.
### Data Management
- Feature hooks: `client/src/data-provider/[Feature]/queries.ts` → `[Feature]/index.ts` → `client/src/data-provider/index.ts`.
- React Query (`@tanstack/react-query`) for all API interactions; proper query invalidation on mutations.
- QueryKeys and MutationKeys in `packages/data-provider/src/keys.ts`.
### Client State Ownership
The client is migrating from Recoil to Jotai. **New state is always Jotai**, including inside a file
that already imports Recoil. For existing state, the unit of conversion is one atom together with
every file that reads or writes it: the two libraries hold different atom objects, so an atom cannot
be half converted, and many files already import both — mixed imports are not a signal that either
choice is fine here. Convert the areas you touch rather than migrating wholesale, and split the work
by who owns the state:
- **Feature-owned state** — atoms a single feature both writes and reads. Convert these to
Jotai as you touch them, with all of their consumers, and keep them inside the feature.
`client/src/store/jotai-utils.ts` carries the equivalents for persisted atoms
(`createStorageAtom`, `createStorageAtomWithEffect`, `createTabIsolatedAtom`), so a Recoil atom
with a localStorage effect has a direct port.
- **App-global state** — preferences and shell state a feature merely consumes
(`maximizeChatSpace`, `showScrollButton`, `enterToSend`, artifact visibility). A feature
that could plausibly be extracted must not reach into `~/store` for these; accept them
through props or a small context the host supplies. When a consumer sits outside the feature you
are changing, leave the atom on Recoil and pass it in — do not convert the shell to make one
feature tidy.
Passing app-global state in — rather than reaching for it — is what lets a feature move to
its own workspace later without a rewrite, and it keeps the Jotai conversion scoped to the
state a feature actually owns instead of dragging the global migration forward early.
### Data-Provider Integration
- Endpoints: `packages/data-provider/src/api-endpoints.ts`
- Data service: `packages/data-provider/src/data-service.ts`
- Types: `packages/data-provider/src/types/queries.ts`
- Use `encodeURIComponent` for dynamic URL parameters.
### Performance
- Prioritize memory and speed efficiency at scale.
- Cursor pagination for large datasets.
- Proper dependency arrays to avoid unnecessary re-renders.
- Leverage React Query caching and background refetching.
---
## Backend Rules (`api/**`, `packages/api/**`)
### Auth cache invalidation
When adding or changing code that mutates user documents, invalidate the auth user document cache
for the affected users. This covers single-user updates as well as bulk role and user mutations.
Without it, OpenID JWT request burst caching can serve a stale `req.user` until its TTL expires.
---
## Development Commands
| Command | Purpose |
|---|---|
| `npm run smart-reinstall` | Install deps (if lockfile changed) + build via Turborepo |
| `npm run reinstall` | Clean install — wipe `node_modules` and reinstall from scratch |
| `npm run backend` | Start the backend server |
| `npm run backend:dev` | Start backend with file watching (development) |
| `npm run build` | Build all compiled code via Turborepo (parallel, cached) |
| `npm run frontend` | Build all compiled code sequentially (legacy fallback) |
| `npm run frontend:dev` | Start frontend dev server with HMR (port 3090, requires backend running) |
| `npm run build:data-provider` | Rebuild `packages/data-provider` after changes |
| `npm run lint:design:prune` | Drop `eslint-suppressions.json` entries whose violations are fixed |
| `npm run lint:design:suppress` | Re-record the design-rule backlog, then prune (needed after a file move) |
- Node.js: v24.16.0
- Database: MongoDB
- Backend runs on `http://localhost:3080/`; frontend dev server on `http://localhost:3090/`
---
## Testing
- Framework: **Jest**, run per-workspace.
- Run tests from their workspace directory: `cd api && npx jest <pattern>`, `cd packages/api && npx jest <pattern>`, etc.
- Frontend tests: `__tests__` directories alongside components; use `test/layout-test-utils` for rendering.
- Cover loading, success, and error states for UI/data flows.
### Typechecking
- **A green build is not a typecheck.** `packages/api`, `packages/client` and `packages/data-schemas`
build with `tsdown` alone, which emits without checking types. Only `packages/data-provider` runs
`tsc` as part of its build.
- Run `npx tsc --noEmit` in the workspace you changed before calling it done. `client` also exposes
it as `npm run typecheck`.
- `packages/client/tsconfig.json` excludes `*.spec.ts(x)` and `*.test.ts(x)`, so test files there are
never typechecked — a type error in a spec surfaces only when the test runs.
- `npm run static-checks` runs the Static Checks CI job locally against your staged files;
`npm run static-checks -- --against origin/dev` reproduces what CI sees for a pull request, and
`npm run static-checks:full` adds the slow gates (TypeScript, config migration tests, unused i18n
keys, unused npm packages).
### Philosophy
- **Real logic over mocks.** Exercise actual code paths with real dependencies. Mocking is a last resort.
- **Spies over mocks.** Assert that real functions are called with expected arguments and frequency without replacing underlying logic.
- **MongoDB**: use `mongodb-memory-server` for a real in-memory MongoDB instance. Test actual queries and schema validation, not mocked DB calls.
- **MCP**: use real `@modelcontextprotocol/sdk` exports for servers, transports, and tool definitions. Mirror real scenarios, don't stub SDK internals.
- Only mock what you cannot control: external HTTP APIs, rate-limited services, non-deterministic system calls.
- Heavy mocking is a code smell, not a testing strategy.
---
## Formatting
Fix all formatting lint errors (trailing spaces, tabs, newlines, indentation) using auto-fix when available. All TypeScript/ESLint warnings and errors **must** be resolved.
`npm run sort-imports` with no arguments rewrites every file under `api/`, `client/src` and the four
`packages/*/src` roots — far beyond what you touched. Always pass explicit paths:
`npm run sort-imports -- path/to/file.ts`.

View file

@ -85,7 +85,6 @@ const { getAppConfig } = require('./services/Config');
const staticCache = require('./utils/staticCache');
const optionalJwtAuth = require('./middleware/optionalJwtAuth');
const noIndex = require('./middleware/noIndex');
const routes = require('./routes');
const agentEventMethods = require('~/models');
/** Route admin file-config MIME patterns through a linear-time engine (ReDoS-safe) on upload. */
@ -517,6 +516,10 @@ if (cluster.isMaster) {
await updateInterfacePerms({ appConfig, getRoleByName, updateAccessPermissions });
});
/* Route modules build their rate limiters as they load, so they load only after the
* startup checks have applied `rateLimits` from librechat.yaml. */
const routes = require('./routes');
/** Load index.html for SPA serving */
const indexPath = path.join(appConfig.paths.dist, 'index.html');
let indexHTML = fs.readFileSync(indexPath, 'utf8');

View file

@ -87,7 +87,6 @@ const createSpaFallback = require('./utils/fallback');
const { getAppConfig } = require('./services/Config');
const staticCache = require('./utils/staticCache');
const noIndex = require('./middleware/noIndex');
const routes = require('./routes');
const agentEventMethods = require('~/models');
/** Route admin file-config MIME patterns through a linear-time engine (ReDoS-safe) on upload. */
@ -273,6 +272,10 @@ const startServer = async () => {
await updateInterfacePermissions({ appConfig, getRoleByName, updateAccessPermissions });
});
/* Route modules build their rate limiters as they load, so they load only after the
* startup checks have applied `rateLimits` from librechat.yaml. */
const routes = require('./routes');
const indexPath = path.join(appConfig.paths.dist, 'index.html');
let indexHTML = fs.readFileSync(indexPath, 'utf8');

View file

@ -28,7 +28,12 @@
}
</style>
<script>
const theme = localStorage.getItem('color-theme');
let theme = null;
try {
theme = localStorage.getItem('color-theme');
} catch (e) {
/* Web Storage denied by browser policy: the shell falls back to the system theme. */
}
const loadingContainerStyle = document.createElement('style');
let backgroundColor;

View file

@ -100,6 +100,7 @@ const TwoFactorScreen: React.FC = React.memo(() => {
value={value != null ? value : ''}
onChange={onChange}
pattern={REGEXP_ONLY_DIGITS}
aria-label={localize('com_ui_2fa_verification_required')}
>
<InputOTPGroup>
<InputOTPSlot index={0} />
@ -131,6 +132,7 @@ const TwoFactorScreen: React.FC = React.memo(() => {
value={value != null ? value : ''}
onChange={onChange}
pattern={REGEXP_ONLY_DIGITS_AND_CHARS}
aria-label={localize('com_ui_backup_code_verification_required')}
>
<InputOTPGroup>
<InputOTPSlot index={0} />
@ -154,7 +156,6 @@ const TwoFactorScreen: React.FC = React.memo(() => {
<Button
type="submit"
variant="submit"
aria-label={localize('com_auth_continue')}
data-testid="login-button"
disabled={isLoading}
className="w-full rounded-2xl px-4 py-3 text-sm font-medium disabled:opacity-80"

View file

@ -13,6 +13,17 @@ import type { TChatProject, TMessage, TConversation } from 'librechat-data-provi
import type { SetterOrUpdater } from 'recoil';
import type { ExtendedFile, FileSetter, ConvoGenerator, TAskFunction } from '~/common';
import type { QueuedMessageContext } from '~/hooks/Chat/useSteering';
import {
cn,
getModelSpec,
hasIncompleteFiles,
removeFocusRings,
getComposerDraftId,
getPendingDraftId,
clearAllDrafts,
getFilesDraftCached,
isPastedTextFileMarked,
} from '~/utils';
import {
useTextarea,
useAutoSave,
@ -32,15 +43,6 @@ import {
useComposerRestoreHost,
BadgeRowProvider,
} from '~/Providers';
import {
cn,
getModelSpec,
hasIncompleteFiles,
removeFocusRings,
getComposerDraftId,
getFilesDraftCached,
isPastedTextFileMarked,
} from '~/utils';
import {
PendingToolApprovalButton,
PendingToolApprovalPanel,
@ -705,12 +707,18 @@ const ChatForm = memo(function ChatForm({
{
answerMode,
steering,
submitMessage,
submitMessage: (message) => {
const result = submitMessage(message);
if (result !== false) {
clearAllDrafts(getPendingDraftId(index));
}
return result;
},
reset: () => methods.reset(),
},
data,
),
[answerMode, steering, submitMessage, methods],
[answerMode, steering, submitMessage, methods, index],
);
return (
@ -753,7 +761,7 @@ const ChatForm = memo(function ChatForm({
data-testid="composer-context-rail"
className={cn(
'mx-4 -mb-3 flex min-w-0 flex-wrap items-center gap-1 rounded-t-2xl',
'border-border-light bg-surface-secondary border px-2 pt-1 pb-4',
'border-border-light bg-surface-secondary border px-2 pb-4 pt-1',
isRTL && 'flex-row-reverse',
)}
>
@ -807,7 +815,7 @@ const ChatForm = memo(function ChatForm({
squared off at the bottom (`rounded-t-theme-surface-lg`) and no disclaimer
follows it — so the action row is the last thing in it, with no
band of padding under the buttons. */
'rounded-t-theme-surface-lg sm:rounded-theme-surface-lg relative flex w-full grow flex-col overflow-hidden',
'relative flex w-full grow flex-col overflow-hidden rounded-t-theme-surface-lg sm:rounded-theme-surface-lg',
composerSurfaceClasses(),
isTextAreaFocused ? composerSurfaceShadow.focused : composerSurfaceShadow.blurred,
/* Temporary-chat accent is a ChatForm-only override, not part of
@ -910,14 +918,14 @@ const ChatForm = memo(function ChatForm({
active={dictation.active}
className={cn(
'pointer-events-none absolute inset-y-2',
isMoreThanThreeRows ? 'right-2 left-5' : 'inset-x-5',
isMoreThanThreeRows ? 'left-5 right-2' : 'inset-x-5',
)}
/>
)}
{/* Sits over the fade scrim in the corner of the input
rather than in its own column beside it, so a long draft
does not push an orphaned control off to the side. */}
<div className="absolute right-2 bottom-1 z-10">
<div className="absolute bottom-1 right-2 z-10">
<CollapseChat
isCollapsed={isCollapsed}
isScrollable={isMoreThanThreeRows}

View file

@ -10,13 +10,15 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { QueryKeys, FileSources, EModelEndpoint } from 'librechat-data-provider';
import { render, screen, within, waitFor, fireEvent } from '@testing-library/react';
import type { TFile, TFileUpload, TConversation } from 'librechat-data-provider';
import type { ChatFormValues } from '~/common';
import type { ChatFormValues, TAskFunction } from '~/common';
import { getDraft, getPendingDraftId, setDraft } from '~/utils';
import ChatForm, { toRestoredComposerFile } from '../ChatForm';
import { ChatContext, ChatFormProvider } from '~/Providers';
import { AuthContextProvider } from '~/hooks/AuthContext';
import store from '~/store';
const mockUpload = jest.fn();
const mockAsk = jest.fn();
jest.mock('librechat-data-provider', () => {
const actual = jest.requireActual('librechat-data-provider');
@ -68,7 +70,7 @@ let commits = 0;
function Harness() {
const [files, setFiles] = useRecoilState(store.filesByIndex(0));
const [isSubmitting] = useRecoilState(store.isSubmittingFamily(0));
const [isSubmitting, setIsSubmitting] = useRecoilState(store.isSubmittingFamily(0));
/* ChatView owns this read and passes it in; the harness stands in for it. */
const [speechSettingsInitialized] = useRecoilState(store.speechSettingsInitialized);
const [, setFilesLoading] = useState(false);
@ -91,7 +93,13 @@ function Harness() {
stopGenerating: () => undefined,
getMessages: () => undefined,
setMessages: () => undefined,
ask: () => undefined,
ask: (...args: Parameters<TAskFunction>) => {
const result = mockAsk(...args);
if (result !== false) {
setIsSubmitting(true);
}
return result;
},
regenerate: () => undefined,
setSiblingIdx: () => undefined,
showPopover: false,
@ -105,7 +113,7 @@ function Harness() {
handleRegenerate: () => undefined,
handleContinue: () => undefined,
}) as unknown as React.ContextType<typeof ChatContext>,
[files, setFiles, isSubmitting],
[files, setFiles, isSubmitting, setIsSubmitting],
);
return (
@ -180,6 +188,7 @@ describe('ChatForm attachments', () => {
global.URL.revokeObjectURL = jest.fn();
(global as unknown as { Image: unknown }).Image = StubImage;
mockUpload.mockReset();
mockAsk.mockReset();
/** The server echoes the id the client sent back as `temp_file_id`. */
mockUpload.mockImplementation((body: FormData) =>
Promise.resolve({ ...uploadResponse, temp_file_id: body.get('file_id') as string }),
@ -258,6 +267,42 @@ describe('ChatForm attachments', () => {
expect(textarea).toHaveFocus();
}, 20000);
test('does not restore an older fragment of the sent message while the run starts', async () => {
renderComposer();
const textarea = await screen.findByTestId('text-input');
const message = 'i would like to learn how to use it for a demo or is it too early days';
await userEvent.type(textarea, message);
setDraft({ id: getPendingDraftId(), value: 'i would like to learn how to use it for a dem' });
await userEvent.click(sendButton());
await waitFor(() =>
expect(mockAsk).toHaveBeenCalledWith(
expect.objectContaining({ text: message }),
expect.anything(),
),
);
expect(textarea).toHaveValue('');
expect(getDraft(getPendingDraftId())).toBe('');
await userEvent.type(textarea, 'a different follow-up');
await waitFor(() => expect(getDraft(getPendingDraftId())).toBe('a different follow-up'));
}, 20000);
test('keeps the draft intact when the normal send is refused', async () => {
mockAsk.mockReturnValue(false);
renderComposer();
const textarea = await screen.findByTestId('text-input');
await userEvent.type(textarea, 'not sent');
setDraft({ id: getPendingDraftId(), value: 'earlier follow-up' });
await userEvent.click(sendButton());
await waitFor(() => expect(mockAsk).toHaveBeenCalled());
expect(textarea).toHaveValue('not sent');
expect(getDraft(getPendingDraftId())).toBe('earlier follow-up');
}, 20000);
test('still returns focus to the textarea after a plain control click', async () => {
renderComposer();
const textarea = await screen.findByTestId('text-input');

View file

@ -29,12 +29,17 @@ jest.mock('~/components/Chat/Messages/Content/ProgressText', () => ({
phase,
inProgressText,
finishedText,
icon,
}: {
phase: 'running' | 'completed' | 'cancelled' | 'failed';
inProgressText: string;
finishedText: string;
icon: React.ReactNode;
}) => (
<div data-testid="progress-text">{phase === 'running' ? inProgressText : finishedText}</div>
<div data-testid="progress-text">
{icon}
{phase === 'running' ? inProgressText : finishedText}
</div>
),
}));
@ -132,6 +137,7 @@ describe('FileAuthoringCall', () => {
);
expect(screen.getByTestId('progress-text')).toHaveTextContent('Updated SKILL.md');
expect(document.querySelector('.lucide-file-pen-line')).not.toBeNull();
});
it('prefers the output diff over the args preview after edit_file completes', () => {

View file

@ -7,6 +7,8 @@ import {
ArrowRightLeft,
FileSearch,
FileText,
FilePlus2,
FilePenLine,
MessageCircleQuestion,
ScrollText,
Brain,
@ -32,6 +34,8 @@ export type ToolIconType =
| 'file_search'
| 'skill'
| 'read_file'
| 'create_file'
| 'edit_file'
| 'bash_tool'
| 'background_tasks'
| 'ask_user_question'
@ -49,6 +53,8 @@ const ICON_MAP: Record<ToolIconType, React.ComponentType<{ className?: string }>
file_search: FileSearch,
skill: ScrollText,
read_file: FileText,
create_file: FilePlus2,
edit_file: FilePenLine,
bash_tool: BashIcon,
background_tasks: ListChecks,
ask_user_question: MessageCircleQuestion,
@ -88,6 +94,9 @@ export function getToolIconType(name: string): ToolIconType {
if (name === 'read_file') {
return 'read_file';
}
if (name === 'create_file' || name === 'edit_file') {
return name;
}
if (name === 'bash_tool' || name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING) {
return 'bash_tool';
}

View file

@ -178,6 +178,45 @@ describe('ActivityPhaseGroup', () => {
expect(screen.getByText(LABEL).parentElement).toHaveClass('flex-1', 'text-left');
});
test.each([
['create_file', '', 'lucide-file-plus-2'],
['edit_file', '', 'lucide-file-pen-line'],
['create_file', 'Created skills/demo/SKILL.md', 'lucide-file-plus-2'],
['create_file', 'Updated AGENTS.md with safe diagnostic guidance', 'lucide-file-pen-line'],
['edit_file', 'Edited AGENTS.md', 'lucide-file-pen-line'],
])(
'shows the file-row glyph on settled and live phase headers for %s: %s',
(name, output, glyph) => {
const part = {
type: ContentTypes.TOOL_CALL,
[ContentTypes.TOOL_CALL]: {
id: 'file-1',
name,
args: '{"path":"AGENTS.md"}',
output,
type: 'tool_call',
},
} as unknown as TMessageContentParts;
const { rerender } = render(
<ActivityPhaseGroup labelPart={labelPart} hasContent spanParts={[part]}>
<div data-testid="phase-content" />
</ActivityPhaseGroup>,
);
expect(screen.getByRole('button', { name: LABEL }).querySelector(`.${glyph}`)).not.toBeNull();
expect(
screen.getByRole('button', { name: LABEL }).querySelector('.lucide-wrench'),
).toBeNull();
rerender(
<ActivityPhaseGroup labelPart={labelPart} hasContent liveParts={[part]}>
<div data-testid="phase-content" />
</ActivityPhaseGroup>,
);
expect(screen.getByRole('button').querySelector(`.${glyph}`)).not.toBeNull();
},
);
test('keeps the focus ring inside the clipped header', () => {
render(
<ActivityPhaseGroup labelPart={labelPart} hasContent>

View file

@ -48,6 +48,15 @@ describe('shared header glyphs', () => {
},
);
it.each([
['create_file', 'lucide-file-plus-2'],
['edit_file', 'lucide-file-pen-line'],
])('renders %s with the same glyph as its file row', (name, glyph) => {
const { container } = render(<StackedToolIcons toolNames={[name]} />);
expect(container.querySelector(`.${glyph}`)).not.toBeNull();
expect(container.querySelector('.lucide-wrench')).toBeNull();
});
it('retains a bounded stack and overflow count', () => {
const { container } = render(
<StackedToolIcons

View file

@ -886,6 +886,26 @@ describe('ToolCallGroup image hoisting', () => {
expect(screen.queryByText(/web_search|file_search|retrieval/)).not.toBeInTheDocument();
});
it('uses the edit glyph for a create_file overwrite without changing its tool label', () => {
renderGroup({
...baseProps,
parts: [
{
part: makePart(
'file-1',
'Updated AGENTS.md with safe diagnostic guidance',
'create_file',
),
idx: 0,
},
],
lastContentIdx: 0,
});
expect(screen.getByTestId('stacked-icons')).toHaveAttribute('data-tool-names', 'edit_file');
expect(screen.getByRole('button', { name: 'Create File' })).toBeInTheDocument();
});
it('keeps repeated action counts and failed-call status in the compact summary', () => {
renderGroup({
...baseProps,

View file

@ -26,6 +26,13 @@ describe('getToolIconType - ACTN-01: Action delimiter detection', () => {
expect(getToolIconType('some_plain_tool')).toBe('generic');
});
it('gives native file authoring tools their row glyphs without changing MCP identity', () => {
expect(getToolIconType('create_file')).toBe('create_file');
expect(getToolIconType('edit_file')).toBe('edit_file');
expect(getToolIconType(`create_file${Constants.mcp_delimiter}remote`)).toBe('mcp');
expect(getToolIconType(`edit_file${Constants.mcp_delimiter}remote`)).toBe('mcp');
});
it('gives the native background-task tool its own icon while preserving MCP identity', () => {
expect(getToolIconType(Constants.CHECK_BACKGROUND_TASK)).toBe('background_tasks');
expect(

View file

@ -1,4 +1,4 @@
import { Tools, Constants, ContentTypes, stripToolCallErrorPrefix } from 'librechat-data-provider';
import { Constants, ContentTypes, stripToolCallErrorPrefix } from 'librechat-data-provider';
import type {
Agents,
TAttachment,
@ -12,9 +12,8 @@ import { getBatchActivityLabelPart, getActivityLabelText } from '~/utils/activit
import { hasPendingApprovalInPart, hasPendingAuthInPart } from '~/utils/groupToolCalls';
import { ASK_USER_QUESTION, getSubmittedAskAnswer } from '~/utils/approval';
import { getToolDisplayLabel, parseToolName } from '~/utils/toolLabels';
import { getToolIconName, getToolMeta, summarizeSpan } from './outcome';
import { boundIntentLabel, getToolCallIntent } from './Parts/intent';
import { isBashProgrammaticToolCall } from './routing';
import { getToolMeta, summarizeSpan } from './outcome';
import { isError } from './ToolOutput';
/** How often a live fold's header may repaint. A streamed intent moves the
@ -246,7 +245,7 @@ export function getSpanIconNames(parts: ReadonlyArray<TMessageContentParts | und
const toolCall = part == null ? undefined : getStandardToolCall(part);
if (toolCall != null) {
const name = toolCall.name ?? '';
icons.add(isBashProgrammaticToolCall(name, toolCall.args) ? Tools.bash_tool : name);
icons.add(getToolIconName(name, toolCall.args, toolCall.output));
continue;
}
const legacy = part == null ? null : getToolMeta(part);

View file

@ -38,6 +38,19 @@ function hasFailedOutput(output: unknown): boolean {
return typeof output === 'string' && isError(output);
}
/** A create_file overwrite displays the edit glyph in its own row. Headers use
* the same identity, without changing the tool name used for labels/counts. */
export function getToolIconName(
name: string,
args?: string | Record<string, unknown>,
output?: string | null,
): string {
if (name === 'create_file' && output?.startsWith('Updated ')) {
return 'edit_file';
}
return isBashProgrammaticToolCall(name, args) ? Tools.bash_tool : name;
}
/**
* Group metadata must agree with the individual card, which resolves its
* outcome from the run step's terminal verdict through `resolveToolCallPhase`.
@ -105,7 +118,7 @@ export function getToolMeta(
* agents" on completion even when the child returned no text. */
const completed = !!tc.output || tc.progress === 1;
const name = tc.name ?? '';
const iconName = isBashProgrammaticToolCall(name, tc.args) ? Tools.bash_tool : name;
const iconName = getToolIconName(name, tc.args, tc.output);
/** Memory tools report failure in prose ("Invalid key ...") that generic
* `isError` parsing does not recognize, so `MemoryCall` classifies it with
* its own predicate. Reuse that here or a persisted call with no terminal

View file

@ -22,9 +22,10 @@ import {
import type * as t from 'librechat-data-provider';
import type { ReactNode } from 'react';
import {
SESSION_KEY,
isSafeRedirect,
getPostLoginRedirect,
dropStoredRedirect,
readStoredRedirect,
clearComposerDraftStorage,
clearRetainedFileDeletions,
openFileDeletionRetention,
@ -226,8 +227,8 @@ const AuthContextProvider = ({
}
const { user, token = '' } = data ?? {};
if (token) {
const storedRedirect = sessionStorage.getItem(SESSION_KEY);
sessionStorage.removeItem(SESSION_KEY);
const storedRedirect = readStoredRedirect();
dropStoredRedirect();
const baseUrl = apiBaseUrl();
const rawPath = window.location.pathname;
const strippedPath =

View file

@ -1221,6 +1221,7 @@
"com_ui_background_finished": "Finished in background",
"com_ui_background_running": "Running in background",
"com_ui_backup_code_number": "Code #{{number}}",
"com_ui_backup_code_verification_required": "Enter your backup code to continue",
"com_ui_backup_codes": "Backup Codes",
"com_ui_backup_codes_regenerate_error": "There was an error regenerating backup codes",
"com_ui_backup_codes_regenerated": "Backup codes have been regenerated successfully",

View file

@ -1,3 +1,4 @@
import './polyfills/storage';
import './polyfills/regeneratorRuntime';
import { createRoot } from 'react-dom/client';
import { initializeI18n } from './locales/i18n';

View file

@ -0,0 +1,74 @@
import { createMemoryStorage, installStorageFallback } from '../storage';
function deniedWindow(): Pick<Window, 'localStorage' | 'sessionStorage'> {
const target = {} as Pick<Window, 'localStorage' | 'sessionStorage'>;
for (const name of ['localStorage', 'sessionStorage']) {
Object.defineProperty(target, name, {
configurable: true,
get() {
throw new DOMException('denied', 'SecurityError');
},
});
}
return target;
}
describe('installStorageFallback', () => {
it('leaves accessible storage untouched', () => {
const storage = createMemoryStorage();
const target = { localStorage: storage, sessionStorage: storage };
expect(installStorageFallback(target)).toEqual([]);
expect(target.localStorage).toBe(storage);
});
it('replaces a throwing getter with a working in-memory storage', () => {
const target = deniedWindow();
expect(() => target.localStorage).toThrow('denied');
expect(installStorageFallback(target)).toEqual(['localStorage', 'sessionStorage']);
target.localStorage.setItem('color-theme', 'dark');
expect(target.localStorage.getItem('color-theme')).toBe('dark');
target.sessionStorage.setItem('lc-rum-queue', '[]');
expect(target.sessionStorage.getItem('lc-rum-queue')).toBe('[]');
expect(target.localStorage.getItem('lc-rum-queue')).toBeNull();
expect(target.localStorage).toBe(target.localStorage);
});
});
describe('createMemoryStorage', () => {
it('implements the Storage methods', () => {
const storage = createMemoryStorage();
expect(storage.getItem('missing')).toBeNull();
storage.setItem('a', '1');
storage.setItem('b', '2');
expect(storage).toHaveLength(2);
expect(storage.key(1)).toBe('b');
expect(storage.key(5)).toBeNull();
storage.removeItem('a');
expect(storage.getItem('a')).toBeNull();
storage.clear();
expect(storage).toHaveLength(0);
});
it('reports stored keys as own properties, as key-scanning readers expect', () => {
const storage = createMemoryStorage();
storage.setItem('textDraft_1', 'hello');
storage.setItem('getItem', 'shadow');
expect(Object.keys(storage)).toEqual(['textDraft_1', 'getItem']);
expect(storage.textDraft_1).toBe('hello');
expect(typeof storage.getItem).toBe('function');
expect(storage.getItem('getItem')).toBe('shadow');
});
it('routes named-property writes and deletes through the stored items', () => {
const storage = createMemoryStorage();
storage.lastModel = 'gpt';
expect(storage.getItem('lastModel')).toBe('gpt');
expect(storage).toHaveLength(1);
expect(Object.keys(storage)).toEqual(['lastModel']);
delete storage.lastModel;
expect(storage.getItem('lastModel')).toBeNull();
expect(storage).toHaveLength(0);
});
});

View file

@ -0,0 +1,87 @@
type StorageName = 'localStorage' | 'sessionStorage';
type StorageHost = Pick<Window, StorageName>;
const STORAGE_NAMES: StorageName[] = ['localStorage', 'sessionStorage'];
/** A session-lived stand-in for Web Storage. Stored keys are reported as own enumerable
* properties, as on a real `Storage`, so `Object.keys(localStorage)` keeps working. */
export function createMemoryStorage(): Storage {
const items = new Map<string, string>();
const storage: Storage = {
get length() {
return items.size;
},
key: (index: number) => Array.from(items.keys())[index] ?? null,
getItem: (key: string) => items.get(String(key)) ?? null,
setItem: (key: string, value: string) => {
items.set(String(key), String(value));
},
removeItem: (key: string) => {
items.delete(String(key));
},
clear: () => items.clear(),
};
return new Proxy(storage, {
get: (target, property, receiver) => {
if (typeof property !== 'string' || property in target) {
return Reflect.get(target, property, receiver);
}
return items.get(property);
},
set: (target, property, value, receiver) => {
if (typeof property !== 'string' || property in target) {
return Reflect.set(target, property, value, receiver);
}
items.set(property, String(value));
return true;
},
deleteProperty: (target, property) => {
if (typeof property !== 'string' || property in target) {
return Reflect.deleteProperty(target, property);
}
items.delete(property);
return true;
},
ownKeys: () => Array.from(items.keys()),
getOwnPropertyDescriptor: (_target, property) => {
if (typeof property !== 'string' || !items.has(property)) {
return undefined;
}
return { value: items.get(property), writable: true, enumerable: true, configurable: true };
},
});
}
function isAccessible(target: StorageHost, name: StorageName): boolean {
try {
return target[name] != null;
} catch {
return false;
}
}
/**
* A browser that denies Web Storage by policy throws a `SecurityError` from the
* `localStorage`/`sessionStorage` getter itself, which would take down every reader in the
* app. Where the getter throws, it is replaced with an in-memory storage for the page's
* lifetime, so the app runs on defaults and remembers nothing across reloads.
*/
export function installStorageFallback(target: StorageHost): StorageName[] {
return STORAGE_NAMES.filter((name) => {
if (isAccessible(target, name)) {
return false;
}
const fallback = createMemoryStorage();
Object.defineProperty(target, name, {
configurable: true,
enumerable: true,
get: () => fallback,
});
return true;
});
}
if (typeof window !== 'undefined') {
installStorageFallback(window);
}

View file

@ -1,7 +1,7 @@
import { useEffect, useState } from 'react';
import { Outlet, useNavigate, useLocation } from 'react-router-dom';
import type { TStartupConfig } from 'librechat-data-provider';
import { DEFAULT_APP_TITLE, REDIRECT_PARAM, SESSION_KEY, setDocumentTitle } from '~/utils';
import { DEFAULT_APP_TITLE, REDIRECT_PARAM, hasStoredRedirect, setDocumentTitle } from '~/utils';
import { TranslationKeys, useLocalize } from '~/hooks';
import { useGetStartupConfig } from '~/data-provider';
import AuthLayout from '~/components/Auth/AuthLayout';
@ -32,8 +32,7 @@ export default function StartupLayout({ isAuthenticated }: { isAuthenticated?: b
useEffect(() => {
if (isAuthenticated) {
const hasPendingRedirect =
new URLSearchParams(window.location.search).has(REDIRECT_PARAM) ||
sessionStorage.getItem(SESSION_KEY) != null;
new URLSearchParams(window.location.search).has(REDIRECT_PARAM) || hasStoredRedirect();
if (!hasPendingRedirect) {
navigate('/c/new', { replace: true });
}

View file

@ -3,6 +3,7 @@ import {
getPostLoginRedirect,
isSafeRedirect,
withBasePath,
hasStoredRedirect,
SESSION_KEY,
} from '../redirect';
@ -271,3 +272,40 @@ describe('persistRedirectToSession', () => {
expect(sessionStorage.getItem(SESSION_KEY)).toBeNull();
});
});
describe('blocked session storage', () => {
/** Embedded and private contexts throw on access rather than answering null. */
const originalDescriptor = Object.getOwnPropertyDescriptor(window, 'sessionStorage');
beforeEach(() => {
Object.defineProperty(window, 'sessionStorage', {
configurable: true,
get() {
throw new DOMException('Storage is blocked in this context', 'SecurityError');
},
});
});
afterAll(() => {
if (originalDescriptor != null) {
Object.defineProperty(window, 'sessionStorage', originalDescriptor);
}
});
it('persisting a destination does not take down the sign-in', () => {
expect(() => persistRedirectToSession('/c/new')).not.toThrow();
});
it('a blocked store reads as empty so the URL param still resolves', () => {
const params = new URLSearchParams('redirect_to=%2Fc%2Fnew');
expect(getPostLoginRedirect(params)).toBe('/c/new');
});
it('no destination resolves when only the blocked store exists', () => {
expect(getPostLoginRedirect(new URLSearchParams())).toBeNull();
});
it('hasStoredRedirect counts a blocked store as empty', () => {
expect(hasStoredRedirect()).toBe(false);
});
});

View file

@ -31,6 +31,35 @@ function resolvesToSameOrigin(url: string): boolean {
}
}
/** Session storage is blocked outright in embedded and private contexts, where it throws on
* access rather than returning null. The destination is a convenience, never a credential, so a
* blocked store must cost the deep link, never the sign-in that carries it: every access
* degrades to "no destination stored". Every other session-storage consumer in the client is
* already guarded this way; the redirect flow was the one reaching for the store bare-handed. */
export const readStoredRedirect = (): string | null => {
try {
return sessionStorage.getItem(SESSION_KEY);
} catch {
return null;
}
};
export const dropStoredRedirect = (): void => {
try {
sessionStorage.removeItem(SESSION_KEY);
} catch {
// A blocked store holds nothing to drop.
}
};
const writeStoredRedirect = (value: string): void => {
try {
sessionStorage.setItem(SESSION_KEY, value);
} catch {
// The destination cannot cross a document swap in this context; the sign-in continues.
}
};
/** Validates that a redirect target is a safe relative path (not an absolute or protocol-relative URL) */
export function isSafeRedirect(url: string): boolean {
if (hasControlChar(url)) {
@ -46,18 +75,21 @@ export function isSafeRedirect(url: string): boolean {
return resolvesToSameOrigin(url);
}
/** Whether a destination is waiting to be consumed; storage that refuses to answer counts as none. */
export const hasStoredRedirect = (): boolean => readStoredRedirect() != null;
/**
* Resolves the post-login redirect from URL params and sessionStorage,
* cleans up both sources, and returns the validated target (or null).
*/
export function getPostLoginRedirect(searchParams: URLSearchParams): string | null {
const urlRedirect = searchParams.get(REDIRECT_PARAM);
const storedRedirect = sessionStorage.getItem(SESSION_KEY);
const storedRedirect = readStoredRedirect();
const target = urlRedirect ?? storedRedirect;
if (storedRedirect) {
sessionStorage.removeItem(SESSION_KEY);
dropStoredRedirect();
}
if (target == null || !isSafeRedirect(target)) {
@ -91,6 +123,6 @@ export function withBasePath(path: string): string {
export function persistRedirectToSession(value: string): void {
if (isSafeRedirect(value)) {
sessionStorage.setItem(SESSION_KEY, value);
writeStoredRedirect(value);
}
}

View file

@ -32,6 +32,15 @@ memory:
personalize: true
tokenLimit: 10000
# Budgets that exist only here, not in the environment, so
# yaml-rate-limits.spec.ts proves librechat.yaml reaches the limiters that route
# modules build while loading. No other spec calls the speech routes.
rateLimits:
stt:
userMax: 2
tts:
userMax: 2
# __E2E_MCP_APP_SANDBOX__
mcpSettings:

View file

@ -0,0 +1,92 @@
import { expect, test } from '@playwright/test';
import type { Page } from '@playwright/test';
import { NEW_CHAT_PATH, messagesView, replyPrompt, replyText, sendMessage } from '../helpers';
/**
* A browser that denies Web Storage by policy throws a `SecurityError` from the
* `localStorage` and `sessionStorage` getters themselves. The denial is in place
* before the document's first script, as it is in a real browser, and the app has
* to run on defaults instead of handing the page to the error boundary.
*/
declare global {
interface Window {
/** Set by the init script when the getters were denied before the app loaded. */
__storageDenied?: boolean;
}
}
async function denyWebStorage(page: Page) {
await page.addInitScript(() => {
for (const name of ['localStorage', 'sessionStorage']) {
Object.defineProperty(window, name, {
configurable: true,
get() {
throw new DOMException('denied', 'SecurityError');
},
});
}
window.__storageDenied = true;
});
}
function collectPageErrors(page: Page): string[] {
const errors: string[] = [];
page.on('pageerror', (error) => errors.push(error.message));
return errors;
}
async function expectNoErrorBoundary(page: Page, errors: string[]) {
await expect(page.getByText('Oops! Something Unexpected Occurred')).toHaveCount(0);
expect(errors, `Unexpected runtime errors: ${errors.join(', ')}`).toEqual([]);
}
test.describe('denied web storage', () => {
test('the chat shell loads when the browser denies Web Storage @scenario:denied-web-storage-loads-the-chat', async ({
page,
}) => {
const errors = collectPageErrors(page);
await denyWebStorage(page);
await page.goto(NEW_CHAT_PATH, { timeout: 15000 });
await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible();
await expect(page.getByRole('main')).toBeVisible();
const storage = await page.evaluate(() => {
window.localStorage.setItem('probe', 'kept');
return {
denied: window.__storageDenied === true,
probe: window.localStorage.getItem('probe'),
session: typeof window.sessionStorage.getItem,
};
});
expect(storage).toEqual({ denied: true, probe: 'kept', session: 'function' });
await expectNoErrorBoundary(page, errors);
});
test('a user can chat and start a new chat when the browser denies Web Storage @scenario:denied-web-storage-chats-and-starts-a-new-chat', async ({
page,
}) => {
const errors = collectPageErrors(page);
await denyWebStorage(page);
await page.goto(NEW_CHAT_PATH, { timeout: 15000 });
await sendMessage(page, replyPrompt('denied-storage'));
await expect(messagesView(page).getByText(replyText('denied-storage'))).toBeVisible({
timeout: 30000,
});
await expect(page).toHaveURL(/\/c\/(?!new$)[^/]+$/);
await page
.getByRole('link', { name: 'New chat', exact: true })
.or(page.getByRole('button', { name: 'New chat', exact: true }))
.filter({ visible: true })
.first()
.click();
await expect(page).toHaveURL(/\/c\/new$/);
await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible();
await expect(messagesView(page).getByText(replyText('denied-storage'))).toHaveCount(0);
await expectNoErrorBoundary(page, errors);
});
});

View file

@ -0,0 +1,264 @@
import { expect, test } from '@playwright/test';
import type { Page, Route } from '@playwright/test';
/**
* An ordinary (already enrolled) 2FA sign-in parks its destination in session storage when the
* login screen mounts, swaps the document to `/` once the challenge is verified, and rebuilds
* the session through the silent refresh. The destination has to survive that document swap and
* be consumed by the sign-in that carried it, and the sign-in itself must never depend on the
* store being writable at all.
*/
/** A non-default destination: reaching it proves the deep link outlived the whole challenge.
* The marker rides the query so no conversation has to exist for the landing to hold. */
const DEEP_LINK = '/c/new?model=test&deep-link=proof';
const DEEP_LINK_PATTERN = /\/c\/new\?model=test&deep-link=proof$/;
/** The second sign-in's own destination: distinct from the first's on purpose. */
const SECOND_LINK = '/c/new?from=second-signin';
const SECOND_LINK_PATTERN = /\/c\/new\?from=second-signin$/;
const DEFAULT_PATTERN = /\/c\/new$/;
const CHALLENGE_PATTERN = /\/login\/2fa\?tempToken=temp-token$/;
const ENROLLED_USER = {
id: 'user-2fa',
_id: 'user-2fa',
name: 'Two Factor User',
username: 'twofactor',
email: 'twofactor@example.com',
provider: 'local',
role: 'USER',
emailVerified: true,
twoFactorEnabled: true,
createdAt: '2026-01-01T00:00:00.000Z',
updatedAt: '2026-01-01T00:00:00.000Z',
};
const json = (route: Route, body: unknown, status = 200) =>
route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(body) });
/** The PWA service worker serves API GETs itself, which would bypass every `page.route` below. */
test.use({ storageState: { cookies: [], origins: [] }, serviceWorkers: 'block' });
/**
* The auth endpoints are intercepted so the ordinary challenge answers deterministically: login
* always demands the temp-token challenge, and the refresh endpoint speaks for the cookie the
* real verify controller sets — dead before verification, live after it, dead again on logout.
*/
async function mockChallengeAuth(page: Page) {
let sessionLive = false;
/** Registered first, so every specific mock below takes precedence. The shell's
* authenticated queries are answered with their empty shapes: letting them 401 against
* the real backend (the bearer is a stand-in for the cookie the real verify controller
* sets) would spin the auth-recovery interceptor, whose login bounce carries the current
* URL as redirect_to — re-declaring a destination mid-test and re-persisting it at the
* login screen. Only /api/config stays real: the login screen renders from it. */
await page.route('**/api/**', async (route) => {
const url = route.request().url();
if (route.request().method() !== 'GET') {
await json(route, {});
return;
}
if (/\/api\/config(\?|$)/.test(url)) {
const response = await route.fetch();
await route.fulfill({ response });
return;
}
if (url.includes('/api/endpoints')) {
await json(route, []);
return;
}
if (url.includes('/api/agents/chat/active')) {
await json(route, []);
return;
}
if (url.includes('/api/presets')) {
await json(route, []);
return;
}
if (/\/api\/tags(\?|$)/.test(url)) {
await json(route, []);
return;
}
if (url.includes('/api/models')) {
await json(route, {});
return;
}
if (url.includes('/api/convos?')) {
await json(route, { conversations: [], pageInfo: { hasMore: false, page: 1, size: 0 } });
return;
}
if (url.includes('/api/convos?pinned')) {
await json(route, { conversations: [], pageInfo: { hasMore: false, page: 1, size: 0 } });
return;
}
if (url.includes('/api/projects')) {
await json(route, { projects: [], hasMore: false });
return;
}
if (url.includes('/api/user/settings/')) {
await json(route, []);
return;
}
if (url.includes('/api/search/enable')) {
await json(route, false);
return;
}
if (url.includes('/api/balance')) {
await json(route, {});
return;
}
if (url.includes('/api/banner')) {
await json(route, { banner: '' });
return;
}
if (url.includes('/api/files/speech')) {
await json(route, { enabled: false });
return;
}
if (url.includes('/api/files')) {
await json(route, []);
return;
}
await json(route, {});
});
await page.route('**/api/auth/login', (route) =>
json(route, { twoFAPending: true, tempToken: 'temp-token' }),
);
await page.route('**/api/auth/refresh', async (route) => {
if (!sessionLive) {
/** The shape the server really sends when no refresh cookie is presented. */
await route.fulfill({
status: 200,
contentType: 'text/html; charset=utf-8',
body: 'Refresh token not provided',
});
return;
}
await json(route, { token: 'auth-token', user: ENROLLED_USER });
});
await page.route('**/api/auth/2fa/verify-temp', async (route) => {
expect(route.request().postDataJSON()).toEqual({ tempToken: 'temp-token', token: '123456' });
sessionLive = true;
await json(route, { token: 'auth-token', user: ENROLLED_USER });
});
await page.route('**/api/auth/logout', async (route) => {
sessionLive = false;
await json(route, {});
});
await page.route('**/api/user', (route) =>
sessionLive ? json(route, ENROLLED_USER) : json(route, { message: 'Unauthorized' }, 401),
);
await page.route('**/api/roles/**', (route) => json(route, { name: 'USER', permissions: {} }));
}
/** Drives one full ordinary-challenge sign-in from the login screen. The password field
* is located by label: SecretInput renders input[type=password], whose role mapping is
* not something the spec should depend on. */
async function signInThroughChallenge(page: Page) {
await page.getByRole('textbox', { name: 'Email' }).fill(ENROLLED_USER.email);
await page.getByLabel('Password').fill('password');
await page.getByRole('button', { name: 'Continue' }).click();
await expect(page).toHaveURL(CHALLENGE_PATTERN);
await page.getByLabel('Enter your 2FA code to continue').fill('123456');
await page.getByRole('button', { name: 'Verify' }).click();
}
/** The authenticated shell shows its account button on wide viewports and its header
* toggle on narrow ones; either mounting proves the sign-in completed and stayed. */
async function expectAuthenticatedShell(page: Page) {
await expect
.poll(
async () =>
(await page.getByTestId('nav-user').isVisible()) ||
(await page.getByTestId('header-open-sidebar-button').isVisible()),
{ timeout: 30000 },
)
.toBe(true);
}
/** Ends the stand-in session the way the app itself would: an in-page logout request
* (page.request would bypass the route mocks) flips the session, and the next document
* load finds no session and keeps the login screen. */
async function endMockSession(page: Page) {
await page.evaluate(() =>
fetch('/api/auth/logout', { method: 'POST', credentials: 'include' }).catch(() => undefined),
);
}
test.describe('ordinary 2FA challenge · deep links', () => {
test('a safe destination survives the challenge and is consumed by that sign-in @scenario:2fa-deep-link-survives-challenge', async ({
page,
}) => {
test.setTimeout(90000);
await mockChallengeAuth(page);
await page.goto(`/login?redirect_to=${encodeURIComponent(DEEP_LINK)}`);
await signInThroughChallenge(page);
await expect(page).toHaveURL(DEEP_LINK_PATTERN, { timeout: 15000 });
/** The authenticated shell mounts and settles here rather than bouncing back to /login. */
await expectAuthenticatedShell(page);
/** Consumed by that sign-in: nothing is left to misdirect a later one. */
expect(await page.evaluate(() => sessionStorage.getItem('post_login_redirect_to'))).toBeNull();
/** A fixed window is the point: the destination must survive the follow-up auth traffic. */
await page.waitForTimeout(3000);
await expect(page).toHaveURL(DEEP_LINK_PATTERN);
/** A reload authenticates through the refreshed session and stays on the deep link. */
await page.reload();
await expectAuthenticatedShell(page);
await expect(page).toHaveURL(DEEP_LINK_PATTERN);
});
test('the sign-in completes when session storage is blocked @scenario:2fa-signin-completes-when-storage-blocked', async ({
page,
}) => {
test.setTimeout(90000);
await mockChallengeAuth(page);
await page.addInitScript(() => {
Object.defineProperty(window, 'sessionStorage', {
/** Configurable because the CI-mode build's storage polyfill replaces a broken
* sessionStorage with its own in-memory shim rather than crashing on a frozen
* property. The shim is per-document, so the challenge's document swap still
* empties it and the landing contract is identical either way. */
configurable: true,
get() {
throw new DOMException('Storage is blocked in this context', 'SecurityError');
},
});
});
await page.goto(`/login?redirect_to=${encodeURIComponent(DEEP_LINK)}`);
/** The store being unwritable must cost the destination, never the sign-in itself. */
await expect(page.getByRole('textbox', { name: 'Email' })).toBeVisible({ timeout: 15000 });
await signInThroughChallenge(page);
await expectAuthenticatedShell(page);
await expect(page).toHaveURL(DEFAULT_PATTERN);
});
test('a consumed destination does not misdirect the next sign-in in the tab @scenario:2fa-destination-consumed-once-across-signins', async ({
page,
}) => {
test.setTimeout(120000);
await mockChallengeAuth(page);
await page.goto(`/login?redirect_to=${encodeURIComponent(DEEP_LINK)}`);
await signInThroughChallenge(page);
await expect(page).toHaveURL(DEEP_LINK_PATTERN, { timeout: 15000 });
await expectAuthenticatedShell(page);
await endMockSession(page);
/** The second sign-in declares a destination of its own: it must land there,
* not on the first sign-in's, and leave nothing behind for a third. */
await page.goto(`/login?redirect_to=${encodeURIComponent(SECOND_LINK)}`);
await expect(page.getByRole('textbox', { name: 'Email' })).toBeVisible({ timeout: 15000 });
await signInThroughChallenge(page);
await expect(page).toHaveURL(SECOND_LINK_PATTERN, { timeout: 15000 });
await expectAuthenticatedShell(page);
expect(await page.evaluate(() => sessionStorage.getItem('post_login_redirect_to'))).toBeNull();
});
});

View file

@ -0,0 +1,75 @@
import { randomUUID } from 'crypto';
import { expect, test } from '@playwright/test';
import type { APIRequestContext } from '@playwright/test';
import cleanupUser from '../../../setup/cleanupUser';
import type { User } from '../../../types';
/**
* `rateLimits` in librechat.yaml is applied during startup, and the speech routes
* build their limiters when their module loads. The harness sets `userMax: 2` for
* `stt` and `tts` in the yaml only, against a built-in default of 50, so the third
* request from a fresh user is refused only when the yaml budget reached the
* limiter.
*/
const YAML_USER_MAX = 2;
async function registerAndLogin(request: APIRequestContext, user: User): Promise<string> {
const registerResponse = await request.post('/api/auth/register', {
data: {
email: user.email,
name: user.name,
password: user.password,
confirm_password: user.password,
},
});
expect(registerResponse.ok()).toBeTruthy();
const loginResponse = await request.post('/api/auth/login', {
data: { email: user.email, password: user.password },
});
expect(loginResponse.ok()).toBeTruthy();
const { token } = (await loginResponse.json()) as { token?: string };
if (!token) {
throw new Error('Expected login response to include a bearer token');
}
return token;
}
test.describe('rate limits from librechat.yaml', () => {
test('the speech routes enforce the yaml budget @scenario:yaml-rate-limits-reach-speech-limiters', async ({
request,
}) => {
const user: User = {
email: `yaml-rate-limits-${randomUUID()}@example.com`,
name: 'Yaml Rate Limits',
password: 'securepassword123',
};
try {
const token = await registerAndLogin(request, user);
const headers = { Authorization: `Bearer ${token}` };
for (const lane of ['stt', 'tts'] as const) {
const statuses: number[] = [];
let body: { message?: string } = {};
for (let attempt = 0; attempt <= YAML_USER_MAX; attempt++) {
const response = await request.post(`/api/files/speech/${lane}`, {
headers,
data: { input: 'hello' },
});
statuses.push(response.status());
if (response.status() === 429) {
body = (await response.json()) as { message?: string };
}
}
expect(statuses.slice(0, YAML_USER_MAX)).not.toContain(429);
expect(statuses[YAML_USER_MAX]).toBe(429);
expect(body.message).toBe(`Too many ${lane.toUpperCase()} requests. Try again later`);
}
} finally {
await cleanupUser(user);
}
});
});

View file

@ -170,6 +170,104 @@ test.describe('mid-run steering and queuing', () => {
await expect(queuedRows(page)).toHaveCount(0);
});
test('keeps a pending fenced-code steer inside the composer at desktop and mobile widths', async ({
page,
}) => {
test.setTimeout(150000);
const label = uniqueLabel('steer-code-layout');
const steerText = `Please use this example:\n\n\`\`\`js\n${`const payload = '${'x'.repeat(300)}';\n`.repeat(12)}\`\`\``;
await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
await selectMockEndpoint(page, PROVIDER_C);
await selectEphemeralMCP(page);
await establishConversation(page, `steer-code-setup-${label}`);
const run = await sendMessage(page, `E2E_STEER_TOOL_REPLY:${label}`);
expect(run.ok()).toBeTruthy();
await typeDuringRun(page, steerText);
const [steerResponse] = await Promise.all([
page.waitForResponse(isSteerRequest, { timeout: 15000 }),
messageInput(page).press('Enter'),
]);
expect(steerResponse.status()).toBe(202);
const row = inFlightSteers(page).filter({ hasText: 'const payload' });
await expect(row.locator('.markdown pre > div')).toHaveCount(1);
await expect(row.getByRole('button', { name: 'Show more' })).toBeInViewport();
for (const width of [1200, 390]) {
await page.setViewportSize({ width, height: 850 });
const bounds = await row.evaluate((element) => {
const stack = element.closest('[data-testid="in-flight-steers"]')?.getBoundingClientRect();
const bubble = element.querySelector('.rounded-theme-surface')?.getBoundingClientRect();
const codeBlock = element.querySelector('.markdown pre > div')?.getBoundingClientRect();
const code = element.querySelector('.markdown pre code');
const codeScroller = code?.parentElement;
if (!stack || !bubble || !codeBlock || !code || !codeScroller) {
throw new Error('Pending steer code block is missing');
}
return {
stackLeft: stack.left,
stackRight: stack.right,
bubbleLeft: bubble.left,
bubbleRight: bubble.right,
codeLeft: codeBlock.left,
codeRight: codeBlock.right,
codeStartLeft: code.getBoundingClientRect().left,
codeScrollWidth: codeScroller.scrollWidth,
codeClientWidth: codeScroller.clientWidth,
};
});
expect(bounds.bubbleLeft).toBeGreaterThanOrEqual(bounds.stackLeft);
expect(bounds.bubbleRight).toBeLessThanOrEqual(bounds.stackRight);
expect(bounds.codeLeft).toBeGreaterThanOrEqual(bounds.bubbleLeft);
expect(bounds.codeRight).toBeLessThanOrEqual(bounds.bubbleRight);
expect(bounds.codeStartLeft).toBeGreaterThanOrEqual(bounds.codeLeft);
await expect(row.locator('.markdown pre').getByText('js', { exact: true })).toBeInViewport();
expect(bounds.codeScrollWidth).toBeGreaterThan(bounds.codeClientWidth);
await expect(row.getByRole('button', { name: 'Show more' })).toBeInViewport();
}
await row.getByRole('button', { name: 'Show more' }).click();
await expect(row.getByRole('button', { name: 'Show less' })).toBeVisible();
});
test('keeps the beginning of a short code steer visible without expanding', async ({ page }) => {
test.setTimeout(150000);
const label = uniqueLabel('steer-code-short');
const steerText = `\`\`\`js\nconst payload = '${'x'.repeat(300)}';\n\`\`\``;
await page.goto(NEW_CHAT_PATH, { timeout: 10000 });
await selectMockEndpoint(page, PROVIDER_C);
await selectEphemeralMCP(page);
await establishConversation(page, `steer-code-setup-${label}`);
const run = await sendMessage(page, `E2E_STEER_TOOL_REPLY:${label}`);
expect(run.ok()).toBeTruthy();
await typeDuringRun(page, steerText);
const [steerResponse] = await Promise.all([
page.waitForResponse(isSteerRequest, { timeout: 15000 }),
messageInput(page).press('Enter'),
]);
expect(steerResponse.status()).toBe(202);
const row = inFlightSteers(page).filter({ hasText: 'const payload' });
await expect(row.locator('.markdown pre code')).toContainText('const payload');
for (const width of [1200, 390]) {
await page.setViewportSize({ width, height: 850 });
const bounds = await row.evaluate((element) => {
const stack = element.closest('[data-testid="in-flight-steers"]')?.getBoundingClientRect();
const code = element.querySelector('.markdown pre code')?.getBoundingClientRect();
if (!stack || !code) {
throw new Error('Pending steer code is missing');
}
return { stackLeft: stack.left, stackRight: stack.right, codeStartLeft: code.left };
});
expect(bounds.codeStartLeft).toBeGreaterThanOrEqual(bounds.stackLeft);
expect(bounds.codeStartLeft).toBeLessThan(bounds.stackRight);
await expect(row.locator('.markdown pre').getByText('js', { exact: true })).toBeInViewport();
await expect(row.getByRole('button', { name: 'Show more' })).toHaveCount(0);
}
});
/**
* Two steers submitted in quick succession must BOTH inject at the next
* tool-batch boundary: the drain is an atomic take-all, the hook returns one

View file

@ -162,7 +162,7 @@ describe('MeterSwatch', () => {
});
});
/** CLAUDE.md requires a deliberately different reference theme, to prove the
/** AGENTS.md requires a deliberately different reference theme, to prove the
* component follows theme data rather than the bundled LibreChat values. */
const referenceTheme: ThemeDefinition = {
version: THEME_VERSION,

View file

@ -1,7 +1,7 @@
#!/usr/bin/env node
/**
* Sorts imports across the LibreChat monorepo per project convention
* (CLAUDE.md § Import Order):
* (AGENTS.md § Code style and performance):
*
* 1. Package value imports — shortest line to longest (`react` always first)
* 2. import type from packages — longest line to shortest
@ -81,7 +81,7 @@ function extractSpec(raw: string): string | null {
return raw.match(/from\s+['"]([^'"]+)['"]/)?.[1] ?? null;
}
/** Applies the CLAUDE.md grouping/length ordering to a run of pure imports. */
/** Applies the AGENTS.md grouping/length ordering to a run of pure imports. */
function sortSegment(stmts: Stmt[]): string[] {
const g1 = stmts
.filter((s) => !s.isType && !s.isLocal)