diff --git a/README.md b/README.md index 1302c858f..4e9228bc4 100644 --- a/README.md +++ b/README.md @@ -26,12 +26,35 @@ --- +## What's New in LibreChat v0.8.8-rc1 + +- **Agent run control:** Interrupt or steer an Agent mid-run, queue follow-up messages, and reclaim, edit, or escalate pending steers. +- **Human-in-the-loop Agents:** Agents stream question progress, ask up to four related questions in one form, pause for input or tool approval, and resume. +- **Unified Agent Builder:** A redesigned Tools marketplace brings together Skills, MCP, Code Interpreter, orchestration, Programmatic Tool Calling, model-spec controls, and per-tool background and intent settings. +- **Readable Agent activity:** Generated activity-group headers, parent phase summaries, and live tool intent labels make long reasoning and tool runs easier to scan. +- **Code Interpreter workflows:** Code and shell tools can run in the background, sandbox images return as viewable artifacts, and highly experimental stateful sessions can reuse prewarmed conversation workspaces. +- **Agent extensibility:** Experimental Agent Plugins can bundle deployment Skills, MCP servers, and opt-in command hooks, while explicit subagents initialize only when selected. +- **Memory, context, and identity:** Agents can manage memory with optional per-agent isolation, expose support contacts safely, and show a more faithful Context Usage gauge. +- **Sharing and files:** Shared conversations show a badge and update at a stable URL, while signed-in viewers can continue them as personal copies. +- **Artifact workflows:** Open previews fullscreen, work with PowerPoint `.potx` templates across upload, search, and code execution, upload shell scripts across common MIME variants, export Mermaid diagrams as SVG or PNG, and download original Office files from the artifact panel. +- **Models and reasoning:** Added GPT-5.6 with Responses API reasoning controls, Claude Opus 5 and Sonnet 5, Gemini 3.7 and 3.6 Flash, and Gemini 3.5 Flash-Lite. +- **Langfuse observability:** Configure encrypted Langfuse connections in-app, let authorized admins open sampled sessions directly, optionally fan out traces by tenant, and suppress central export per run. +- **Administration and security:** Delegate config sections, encrypt registered secrets, enforce SSRF checks for speech, OCR, and web tools, and generate unique temporary credentials when secrets are blank. +- **Messages and navigation:** Right-aligned user turns, unified multi-part editing, full-message copy, a dock-style message rail, virtualized search, smooth streaming, and faster Agent startup. +- **Streaming and tool reliability:** Adaptive provider smoothing, Redis delta batching, dynamic MCP tool refresh, parsed MCP response media types, runtime OAuth recovery, and Agent stream circuit breakers improve long-running workflows. +- **Deployment and reliability:** Added configurable HTTP timeouts, Amazon DocumentDB 5.0+ support, low-noise Redis and browser observability, and a rolling-upgrade-safe generation protocol. + +Read the [full v0.8.8-rc1 changelog](https://www.librechat.ai/changelog/v0.8.8-rc1). + +--- + This repository powers **[www.librechat.ai](https://www.librechat.ai)**: the docs, guides, blog, and changelog for LibreChat. It is a [Next.js](https://nextjs.org) application built on [Fumadocs](https://fumadocs.dev), with content authored in MDX. > Looking for the LibreChat app itself? It lives at **[danny-avila/LibreChat](https://github.com/danny-avila/LibreChat)**. Open code and product issues there, and documentation issues here. ## Table of Contents +- [What's New in LibreChat v0.8.8-rc1](#whats-new-in-librechat-v088-rc1) - [Features](#features) - [Tech Stack](#tech-stack) - [Getting Started](#getting-started) diff --git a/content/changelog/config_v1.3.14.mdx b/content/changelog/config_v1.3.14.mdx new file mode 100644 index 000000000..d9b716517 --- /dev/null +++ b/content/changelog/config_v1.3.14.mdx @@ -0,0 +1,207 @@ +--- +date: 2026-08-14 +title: โš™๏ธ Config v1.3.14 +version: '1.3.14' +--- + +- Updated Agents endpoint capabilities + - Added `memory` and `ask_user_question` to the default capability list + - Added highly experimental, opt-in `stateful_code_sessions` for reusable Code Interpreter workspaces; behavior and configuration may change substantially during experimentation + - Added opt-in `run_in_background`; Code Interpreter tools are background-eligible by default while MCP tools remain per-tool opt-ins + - Added opt-in `tool_intents` for live model-written labels on native and selected MCP tool calls + +- Added Agent activity-group settings + - `activityLabel` enables generated one-line headers for contiguous reasoning and tool-call blocks + - `activityModel`, `activityEndpoint`, and `activityPrompt` select and configure the header model call + - `activityMaxPerRun` and `activityCharLimit` bound additional calls and prompt input + - Fields can be set under `endpoints.all`, `endpoints.agents`, or the backing provider/custom endpoint and resolve independently by precedence + +- Added parent Agent activity-phase settings + - `activityPhaseLabel` generates a collapsed summary for run phases containing at least two logical activities + - `activityPhaseModel`, `activityPhaseEndpoint`, and `activityPhasePrompt` configure the summary model call + - `activityPhaseMaxPerRun` defaults to `5`; `activityCharLimit` also bounds phase-summary evidence + - Phase settings fall back through activity-label, title-model, and current-run settings and use the same endpoint configuration precedence + - Short progress remains grouped, substantial answer text closes the active phase before the result, and later activity blocks can create another phase in the same run + - Persisted phase boundaries are rebased after content compaction so they remain aligned after reload + +- Added `endpoints.agents.toolApproval` + - Enables human approval for matching Agent tool calls + - Supports `default`, `dontAsk`, and `bypass` modes plus glob-based `allow`, `deny`, and `ask` rules + - Supports trusted programmatic hooks for context-aware approval policy; hooks can only make the static policy stricter + +- Added `endpoints.agents.checkpointer` + - Persists paused Ask User and tool-approval runs so they can resume later + - Uses MongoDB by default with a 24-hour TTL + - Supports configurable collection names and a process-local `memory` mode for development + +- Added `summarization.retainRecent` + - `turns` preserves a configurable number of recent complete conversation turns outside the summary + - `tokens` sets a recent token-retention budget + +- Updated automatic memory extraction + - `memory.agent.enabled: true` is now required to run the automatic memory agent + - Manual memories and Agent memory tools remain available when automatic extraction is off + +- Added model spec controls + - `showInMenu` can hide a spec from the selector while retaining trusted explicit `spec` access + - `memory` equips an ephemeral Agent with memory tools + - `askUserQuestion` enables durable question-and-resume flows + - `runInBackground` now accepts a boolean or resolved tool-ID list; `false` or `[]` opts out of background-native code tools + - `describeIntent` accepts a boolean or resolved tool-ID list for live tool intent labels + +- Added OpenAI reasoning controls + - `reasoning_mode` supports `standard` and `pro` + - `reasoning_context` supports `auto`, `current_turn`, and `all_turns` + - `reasoning_effort` now supports `max` on compatible models + - GPT-5.6 reasoning requests default to the Responses API unless `useResponsesApi: false` is set explicitly + +- Added top-level `langfuse` tenant configuration + - Stores enabled state, public key, encrypted secret key, verified project ID, masked `secretKeyPreview`, and an approved destination key + - Added an admin-only **Settings โ†’ Langfuse** connection flow with server-side credential verification + - Complete environment credentials take precedence in single-tenant deployments; fanout availability remains deployment-controlled + - Removed the legacy `displaySecretKey` and nested `fanout.enabled` fields + - Added opt-in Compose and Helm fanout deployment settings for central and tenant-scoped trace export + - Added `LANGFUSE_FANOUT_LISTEN_ADDR` to override the gateway's default `:4318` listen address + - Added `LANGFUSE_PROJECT_ID`, `LANGFUSE_TRACING_ENABLED`, and deterministic `LANGFUSE_SAMPLE_RATE` + - Authorized administrators can open a sampled conversation's Langfuse session directly from the Context Usage breakdown + +- Expanded admin config secret handling + - Registered OCR, speech, web-search, Assistants, Azure Assistants, and Langfuse keys are encrypted and redacted on admin writes and reads + - `endpoints.custom[].apiKey` literals are encrypted; environment references and `user_provided` remain passthrough values + - Registered secret fields expose server-generated `Preview` companions + +- Added Node.js HTTP server timeout settings + - `HTTP_KEEP_ALIVE_TIMEOUT_MS` and `HTTP_KEEP_ALIVE_TIMEOUT_BUFFER_MS` + - `HTTP_HEADERS_TIMEOUT_MS` and `HTTP_REQUEST_TIMEOUT_MS` + - Values are non-negative milliseconds; `0` disables the corresponding timeout + +- Added Code Interpreter runtime settings + - `CODE_SANDBOX_PREWARM` controls stateful sandbox prewarming + - `CODE_SANDBOX_COLD_AFTER_MS` controls when tracked sandboxes are treated as cold + - `LIBRECHAT_CODE_IMAGE_CHUNK_BYTES` controls transport chunk size for sandbox images returned by `read_file` + +- Added experimental Agent Plugin runtime settings + - `DEPLOYMENT_PLUGINS_DIR` selects the startup-loaded plugin package directory and defaults to `./plugin` + - `DEPLOYMENT_PLUGIN_DATA_DIR` selects the persistent per-plugin data root and defaults to `./data/plugins` + - Agent Plugins `1.0.0` can bundle deployment Skills and MCP servers + - `DEPLOYMENT_PLUGIN_HOOKS=true` opts trusted plugins into `command` hook execution on the API host; hooks are ignored with a warning by default + - Command hooks receive bounded lifecycle payloads over standard input, run with a minimal environment plus explicit `allowedEnvVars`, and can return event-appropriate decisions + +- Updated GitHub Skill Sync isolation + - Valid Skills can publish when another Skill in the source is invalid or conflicts + - Partially successful runs report `partial` with bounded skipped-Skill counts and details + - Skipped Skills preserve last-known-good mirrors; source authentication, rate-limit, lock-loss, and rollback failures remain fatal + +- Updated `speech.speechTab` engine defaults + - `engineSTT` accepts `browser` and `external`; legacy `openai` and `azureOpenAI` values normalize to `external` + - `engineTTS` accepts `browser` and `external`; legacy provider values normalize to `external` + - Saved legacy values are migrated before speech settings initialize, and unavailable external engines fall back to `browser` + +- Added file upload runtime settings + - `FILE_UPLOAD_SSE_ENABLED` keeps long-running uploads alive with SSE heartbeats + - `REMOTE_FILE_FETCH_TIMEOUT_MS` limits server-side remote file download time + - `REMOTE_FILE_FETCH_MAX_BYTES` limits server-side remote file download size + - `FILE_USAGE_USER_MAX` and `FILE_USAGE_USER_WINDOW` limit queued-attachment TTL renewal requests separately from upload limits + - Shell MIME variants `application/x-shellscript` and `text/x-shellscript` normalize to the canonical `application/x-sh` before endpoint allowlist checks + - Rejected uploads now return their specific unsupported-file message and HTTP status instead of a generic server error + +- Expanded PowerPoint template handling + - `.potx` files are recognized by their standard MIME type across uploads and SharePoint imports + - PowerPoint templates can use file search, Code Interpreter, OCR, and inline presentation previews + +- Added separate authentication token-submission rate limits + - `RESET_PASSWORD_SUBMISSION_MAX` and `RESET_PASSWORD_SUBMISSION_WINDOW` limit password-reset token validation independently from reset-email requests + - `VERIFY_EMAIL_SUBMISSION_MAX` and `VERIFY_EMAIL_SUBMISSION_WINDOW` limit verification-token validation independently from email resends + - Added separate violation-score controls for both submission limiters + +- Added Agent conversation control `STEER_MAX_LENGTH` + - Caps the length of one mid-run steering message + +- Added `GENERATION_PROTOCOL_VERSION` + - Supports the rolling-upgrade-safe cutover to interrupt, recovery, and durable queue protocol v2 on Redis-backed deployments + +- Added section-scoped administrator configuration access + - Read responses are filtered to sections the administrator can access + - Managing a configuration section also grants read access to that section + - Every mutation of the base `__base__` profile requires broad `manage:configs`; section-scoped management applies to role, group, and user overrides + +- Updated request-scoped MCP server behavior + - Agent Builder attaches servers that use `{{LIBRECHAT_BODY_*}}` as a whole and resolves their tool catalog during the active run + - OAuth completion stores authorization but defers the request-scoped connection until chat context is available + +- Updated MCP server instruction handling + - Preserves the configured `serverInstructions` declaration separately from instructions fetched during inspection + - Keeps `true` declarations and literal overrides authoritative across cached registry reloads + - Refreshes Redis-backed registry entries written by earlier builds during initialization + +- Updated MCP transport compatibility + - Upgraded `@modelcontextprotocol/sdk` to `1.30.0` + - Streamable HTTP responses are classified by their parsed `Content-Type` media type instead of substring matching + - Individual STDIO messages now have the SDK's 10 MB default buffer limit and fail the transport when exceeded + +- Updated transaction recording + - `transactions.enabled: false` is honored on the token-count fallback path when a provider does not return usable stream usage + - `balance.enabled: true` continues to require transaction recording regardless of the transaction setting + +- Updated Admin Panel configuration and Google SSO + - `ADMIN_PANEL_URL` now also exposes an admin-only link under **Settings -> General** + - Google admin OAuth requests offline access and can refresh the panel session while rechecking current account, tenant, domain, ban, and admin-access policy + +- Added authentication and permission cache settings + - `ALLOW_EMAIL_LOGIN_OVERRIDE` permits audited direct API email login while the regular email login UI is disabled + - `AUTH_USER_CACHE_MODE=on` opts into a short Redis-backed authenticated-user cache + - `USER_PRINCIPALS_CACHE_TTL_MS`, `USER_PRINCIPALS_LOCK_TTL_MS`, and `USER_PRINCIPALS_LOCK_WAIT_MS` tune ACL principal caching and cross-process cache builds + +- Added `{{LIBRECHAT_USER_TERMSACCEPTEDAT}}` + - Makes the recorded terms acceptance timestamp available to MCP and custom endpoint header templates + - Existing accepted users can be backfilled with `npm run migrate:terms-timestamp` + +- Updated built-in model defaults + - Added GPT-5.6 Sol, Terra, and Luna + - Added Claude Sonnet 5, including Bedrock model IDs + - Added Gemini 3.6 Flash and Gemini 3.5 Flash-Lite + - Added Gemini 3.7 Flash for Google AI Studio and Vertex AI with a 1,048,576-token context window + - Defaults Gemini 3.7 Flash to `MEDIUM` thinking and maps its unsupported `MINIMAL` level to `LOW` + - Uses introductory Gemini 3.6/3.7 Flash input, output, and cache pricing through December 31, 2026 + +- Added Agent stream circuit breakers + - `endpoints.agents.maxToolCallArgBytes` limits one streamed tool call's cumulative argument bytes + - `maxDeltaEventsPerTurn` limits stream events from one model generation + - `maxToolCallArgBytesByTool` provides per-tool overrides, including the shipped 128 KiB `create_file` allowance + +- Added `STREAM_DELTA_COALESCE_MS` + - Optionally batches Redis delta publications to reduce round trips and Redis CPU at high token rates + - Defaults off; `25` ms is recommended and values are capped at `1000` + - Must be enabled only after every replica supports batch frames + +- Added `LANGFUSE_FANOUT_CENTRAL_MEDIA_UPLOAD_DISABLED` + - Disables app-side media upload creation for central and fallback collector traces without changing tenant-routed media + +- Updated custom PII filters to use RE2 + - Custom patterns now run on a linear-time engine and are validated at config load + - Backreferences and lookaround are not supported + +- Updated administrator-configured file MIME patterns to use RE2 on the server + - Invalid patterns are skipped and logged + - If every configured pattern is invalid, the resulting list fails closed and rejects every file + +- Added `allowedAddresses` to `speech.tts`, `speech.stt`, and `ocr` + - Speech and OCR requests now enforce private-address SSRF checks at connect time and disable redirects + - Exact trusted private host:port entries bypass the block without restricting public destinations + - Literal private destinations remain blocked through a proxy unless exempted; proxied hostname egress remains the proxy's responsibility + +- Added `webSearch.allowedAddresses` + - Web search, scrape, and rerank connections now block private, loopback, link-local, and cloud-metadata destinations at connect time + - The field exempts exact trusted private host:port services without becoming a public-host allowlist + - Self-hosted SearXNG, Firecrawl, Jina, or compatible provider endpoints on private networks must be exempted + +- Updated provider stream smoothing + - OpenAI, custom, Anthropic, Google, Bedrock, and Agents SDK-backed streams use adaptive smoothing with a 25 ms target by default + - Endpoint `streamRate` remains in effect when `endpoints.all` omits it, and an explicit `0` disables adaptive smoothing + +- Removed published credential and search defaults + - Blank `CREDS_KEY`, `CREDS_IV`, `JWT_SECRET`, and `JWT_REFRESH_SECRET` values generate temporary credentials, reusing `LIBRECHAT_TEMP_CREDENTIALS_PATH` when available + - Bundled Compose files persist `/app/data/.env.temp`; production and multi-replica deployments must still provide permanent shared values + - `SEARCH` now defaults to `false` and `MEILI_MASTER_KEY` is blank so operators must opt in with a unique key + +- Updated the config version to `1.3.14` diff --git a/content/changelog/v0.8.8-rc1.mdx b/content/changelog/v0.8.8-rc1.mdx new file mode 100644 index 000000000..d39acd46c --- /dev/null +++ b/content/changelog/v0.8.8-rc1.mdx @@ -0,0 +1,428 @@ +--- +date: 2026-08-14 +title: ๐Ÿš€ LibreChat v0.8.8-rc1 +description: The v0.8.8-rc1 release of LibreChat +version: '0.8.8-rc1' +--- + +## What's Changed + +### ๐Ÿž๏ธ Highlights + +- Interrupt or steer Agent runs in progress, or queue the next message +- Agents can ask up to four related questions in one form, pause for input or approval, then resume +- Redesigned Agent Builder with a unified Tools marketplace and background tools +- Experimental Agent Plugins with deployment Skills, MCP servers, and opt-in command hooks +- Activity groups, parent phase summaries, and live tool intent labels +- Experimental stateful Code Interpreter sessions with reusable conversation workspaces +- Agent-managed memory with optional per-agent isolation +- Stable shared-link updates, active-link badges, and personal copies +- Fullscreen artifact previews and Mermaid SVG/PNG export +- In-app Langfuse connections, tenant fanout, and admin session links +- Unified message layouts, multi-part response editing, and full-message copy +- Smooth text fade-in, adaptive streaming, and live MCP tool-catalog refresh +- Stronger SSRF guards for speech, OCR, and web tools +- Provider updates: GPT-5.6, Claude Opus 5 and Sonnet 5, Gemini 3.7 and 3.6 Flash, and Gemini 3.5 Flash-Lite + +--- + +### โœจ Features + +- ๐Ÿ•’ feat: Track terms acceptance timestamp by [@berry-13](https://github.com/berry-13) in [#10810](https://github.com/danny-avila/LibreChat/pull/10810) +- ๐Ÿ”„ feat: Continue Shared Conversations as Personal Copies by [@berry-13](https://github.com/berry-13) in [#13714](https://github.com/danny-avila/LibreChat/pull/13714) +- ๐Ÿช feat: HITL Tool Approval Scaffolding (Slice A) by [@danny-avila](https://github.com/danny-avila) in [#12938](https://github.com/danny-avila/LibreChat/pull/12938) +- ๐Ÿง  feat: Add Memory as an Agent Capability with Inline Tools and Ephemeral Badge by [@danny-avila](https://github.com/danny-avila) in [#13869](https://github.com/danny-avila/LibreChat/pull/13869) +- ๐Ÿ“‡ feat: Agent Contact Visibility with Owner Fallback by [@peeeteeer](https://github.com/peeeteeer) in [#13663](https://github.com/danny-avila/LibreChat/pull/13663) +- ๐ŸชŸ feat: Faithful Over-Window Context Estimate via Prune Mirror and Overhead Reserve by [@danny-avila](https://github.com/danny-avila) in [#13959](https://github.com/danny-avila/LibreChat/pull/13959) +- ๐Ÿชญ feat: Add opt-in Langfuse fanout gateway + collector by [@upman](https://github.com/upman) in [#13872](https://github.com/danny-avila/LibreChat/pull/13872) +- ๐Ÿช feat: Human-in-the-Loop Runtime - Tool Approval + Ask-User-Question (Slice B) by [@danny-avila](https://github.com/danny-avila) in [#13942](https://github.com/danny-avila/LibreChat/pull/13942) +- ๐Ÿช— feat: Dock-Style Fisheye Nav Rail With Instant Hover Preview by [@danny-avila](https://github.com/danny-avila) in [#14021](https://github.com/danny-avila/LibreChat/pull/14021) +- ๐Ÿค– feat: Add Claude Sonnet 5 Support by [@danny-avila](https://github.com/danny-avila) in [#14042](https://github.com/danny-avila/LibreChat/pull/14042) +- ๐Ÿฅท feat: Add `showInMenu` Option to Model Specs by [@alexkorep](https://github.com/alexkorep) in [#14034](https://github.com/danny-avila/LibreChat/pull/14034) +- ๐Ÿซท feat: Exclude File Authoring Tools From Eager Execution by [@danny-avila](https://github.com/danny-avila) in [#14051](https://github.com/danny-avila/LibreChat/pull/14051) +- ๐Ÿช feat: Configurable Tool-Approval Policy via Programmatic Hooks by [@danny-avila](https://github.com/danny-avila) in [#14025](https://github.com/danny-avila/LibreChat/pull/14025) +- ๐Ÿงน feat: Eager HITL Checkpoint Cleanup (Expiry + Deletion) & Full-Wiring E2E by [@danny-avila](https://github.com/danny-avila) in [#14123](https://github.com/danny-avila/LibreChat/pull/14123) +- ๐Ÿงฐ feat: Redesign Agent Builder with Unified Tools Marketplace, Skills & Orchestration by [@berry-13](https://github.com/berry-13) in [#13952](https://github.com/danny-avila/LibreChat/pull/13952) +- ๐Ÿ“ก feat: add rum browser page-load diagnostics by [@upman](https://github.com/upman) in [#14106](https://github.com/danny-avila/LibreChat/pull/14106) +- ๐ŸŽš๏ธ feat: Explicit "Use All Skills" Toggle in the Skills Section by [@berry-13](https://github.com/berry-13) in [#14125](https://github.com/danny-avila/LibreChat/pull/14125) +- ๐Ÿ™‹ feat: ask_user_question - agent-initiated questions with durable pause/resume by [@danny-avila](https://github.com/danny-avila) in [#14139](https://github.com/danny-avila/LibreChat/pull/14139) +- ๐Ÿ—‚๏ธ feat: Per-Agent Memory Partitions by [@danny-avila](https://github.com/danny-avila) in [#14084](https://github.com/danny-avila/LibreChat/pull/14084) +- ๐Ÿค– feat: Add GPT-5.6 (Sol/Terra/Luna) OpenAI Models by [@danny-avila](https://github.com/danny-avila) in [#14206](https://github.com/danny-avila/LibreChat/pull/14206) +- ๐Ÿชญ feat: support per-run central export suppression by [@upman](https://github.com/upman) in [#14207](https://github.com/danny-avila/LibreChat/pull/14207) +- โœจ feat: stateful_code_sessions capability for warm Code API sandbox sessions (experimental) by [@danny-avila](https://github.com/danny-avila) in [#14150](https://github.com/danny-avila/LibreChat/pull/14150) +- ๐Ÿง  feat: Add GPT-5.6 reasoning.mode + reasoning.context (Responses API) by [@danny-avila](https://github.com/danny-avila) in [#14233](https://github.com/danny-avila/LibreChat/pull/14233) +- ๐Ÿงต feat: Background Tool Calls for Agents & Model Specs by [@danny-avila](https://github.com/danny-avila) in [#14197](https://github.com/danny-avila/LibreChat/pull/14197) +- ๐Ÿ—๏ธ feat: Encrypted Langfuse Fanout Config by [@dustinhealy](https://github.com/dustinhealy) in [#14107](https://github.com/danny-avila/LibreChat/pull/14107) +- ๐Ÿงญ feat: Mid-Run Steering and Queued Messages for Agent Runs by [@danny-avila](https://github.com/danny-avila) in [#14220](https://github.com/danny-avila/LibreChat/pull/14220) +- โ™จ๏ธ feat: Prewarm Stateful Code Sandboxes with Cold-Boot UX Feedback by [@danny-avila](https://github.com/danny-avila) in [#14239](https://github.com/danny-avila/LibreChat/pull/14239) +- ๐Ÿ“› feat: Add Client Name Header to Tavily Search Requests by [@manisrinivasan2k1](https://github.com/manisrinivasan2k1) in [#14082](https://github.com/danny-avila/LibreChat/pull/14082) +- ๐Ÿ’ฌ feat: Explain Steering & Queuing at Every User-Facing Surface by [@danny-avila](https://github.com/danny-avila) in [#14260](https://github.com/danny-avila/LibreChat/pull/14260) +- ๐Ÿ–ผ๏ธ feat: Return Sandbox Images From `read_file` as Viewable Artifacts by [@danny-avila](https://github.com/danny-avila) in [#14277](https://github.com/danny-avila/LibreChat/pull/14277) +- feat: add low-noise Redis observability by [@upman](https://github.com/upman) in [#14309](https://github.com/danny-avila/LibreChat/pull/14309) +- โœ‹ feat: Add Reclaim-Gated Controls to In-Flight Steers by [@danny-avila](https://github.com/danny-avila) in [#14321](https://github.com/danny-avila/LibreChat/pull/14321) +- ๐Ÿซง feat: Float In-Flight Steers Over the Thread with Collapsible Content by [@danny-avila](https://github.com/danny-avila) in [#14365](https://github.com/danny-avila/LibreChat/pull/14365) +- โšก feat: Add Gemini 3.6 Flash and Gemini 3.5 Flash-Lite Support by [@danny-avila](https://github.com/danny-avila) in [#14369](https://github.com/danny-avila/LibreChat/pull/14369) +- ๐Ÿงต feat: Native Background Execution for Code Interpreter Tools by [@danny-avila](https://github.com/danny-avila) in [#14386](https://github.com/danny-avila/LibreChat/pull/14386) +- โœณ๏ธ feat: Claude Opus 5 Support by [@danny-avila](https://github.com/danny-avila) in [#14422](https://github.com/danny-avila/LibreChat/pull/14422) +- โฑ๏ธ feat: Configurable HTTP Server Timeouts by [@danny-avila](https://github.com/danny-avila) in [#14481](https://github.com/danny-avila/LibreChat/pull/14481) +- ๐Ÿ•ถ feat: Generalize Admin Config Secret Redaction by [@dustinhealy](https://github.com/dustinhealy) in [#14509](https://github.com/danny-avila/LibreChat/pull/14509) +- ๐Ÿท๏ธ feat: Activity Groups With Fast-Model Headers by [@danny-avila](https://github.com/danny-avila) in [#14391](https://github.com/danny-avila/LibreChat/pull/14391) +- ๐Ÿ—๏ธ feat: Custom Endpoint API Key Encryption via Array Secret Registry by [@danny-avila](https://github.com/danny-avila) in [#14510](https://github.com/danny-avila/LibreChat/pull/14510) +- ๐ŸŽฏ feat: Tool Intent Label Capability (tool_intents) by [@danny-avila](https://github.com/danny-avila) in [#14499](https://github.com/danny-avila/LibreChat/pull/14499) +- ๐Ÿชข feat: Langfuse Fanout Connection Setting by [@danny-avila](https://github.com/danny-avila) in [#14108](https://github.com/danny-avila/LibreChat/pull/14108) +- ๐Ÿ›‘ feat: Preemptive Steer - Backend Interrupt & Steer by [@danny-avila](https://github.com/danny-avila) in [#14518](https://github.com/danny-avila/LibreChat/pull/14518) +- ๐ŸŽฏ feat: Per-Tool Intent Labels for Model Specs by [@danny-avila](https://github.com/danny-avila) in [#14526](https://github.com/danny-avila/LibreChat/pull/14526) +- โšก feat: Interrupt & Steer, Client by [@danny-avila](https://github.com/danny-avila) in [#14528](https://github.com/danny-avila/LibreChat/pull/14528) +- ๐Ÿงต feat: Background-Native Code Execution Tools by [@danny-avila](https://github.com/danny-avila) in [#14532](https://github.com/danny-avila/LibreChat/pull/14532) +- ๐ŸŽฏ feat: Render Tool Intent as the Live Tool-Call Label by [@danny-avila](https://github.com/danny-avila) in [#14536](https://github.com/danny-avila/LibreChat/pull/14536) +- ๐ŸŽฏ feat: Per-Tool Intent Label Toggles in the Agent Builder by [@danny-avila](https://github.com/danny-avila) in [#14550](https://github.com/danny-avila/LibreChat/pull/14550) +- โšก feat: Reliable Interrupt & Steer Escalation and Recovery by [@danny-avila](https://github.com/danny-avila) in [#14558](https://github.com/danny-avila/LibreChat/pull/14558) +- ๐Ÿ’ฌ feat: Interim Progress Card for Streaming Q&A Calls by [@danny-avila](https://github.com/danny-avila) in [#14576](https://github.com/danny-avila/LibreChat/pull/14576) +- ๐Ÿšฆ feat: Configurable Circuit Breakers for Runaway Streamed Tool Args by [@danny-avila](https://github.com/danny-avila) in [#14613](https://github.com/danny-avila/LibreChat/pull/14613) +- โšก feat: Coalesce Redis Streaming Delta Publications into Windowed Batches by [@danny-avila](https://github.com/danny-avila) in [#14614](https://github.com/danny-avila/LibreChat/pull/14614) +- ๐Ÿ”’ feat: Add allowedAddresses Exemption to Speech (STT/TTS) and OCR Config Schemas by [@dustinhealy](https://github.com/dustinhealy) in [#14559](https://github.com/danny-avila/LibreChat/pull/14559) +- ๐ŸŒŠ feat: Wire Adaptive Stream Smoothing Across Google, Bedrock, and Zero-Disable Semantics by [@danny-avila](https://github.com/danny-avila) in [#14660](https://github.com/danny-avila/LibreChat/pull/14660) +- ๐Ÿ”— feat: Admin Panel Link in Settings for Admins by [@dustinhealy](https://github.com/dustinhealy) in [#14662](https://github.com/danny-avila/LibreChat/pull/14662) +- ๐Ÿ‘‹ feat: Day-Aware Landing Greeting Schedule by [@berry-13](https://github.com/berry-13) in [#14633](https://github.com/danny-avila/LibreChat/pull/14633) +- ๐Ÿ”‘ feat: Refresh-Capable Google Admin OAuth Sessions by [@dustinhealy](https://github.com/dustinhealy) in [#13832](https://github.com/danny-avila/LibreChat/pull/13832) +- ๐Ÿ›ก๏ธ feat: Add Batched MCP Authority Proofs by [@danny-avila](https://github.com/danny-avila) in [#14688](https://github.com/danny-avila/LibreChat/pull/14688) +- ๐Ÿช feat: Add Claude Hook Compatibility Layer by [@danny-avila](https://github.com/danny-avila) in [#14412](https://github.com/danny-avila/LibreChat/pull/14412) +- โ›ถ feat: add fullscreen artifact previews by [@berry-13](https://github.com/berry-13) in [#14585](https://github.com/danny-avila/LibreChat/pull/14585) +- ๐Ÿ”Œ feat: Add Agent Plugins (Experimental) by [@danny-avila](https://github.com/danny-avila) in [#14704](https://github.com/danny-avila/LibreChat/pull/14704) +- ๐Ÿ”— feat: Shared Conversation Badge and Stable Share Links by [@berry-13](https://github.com/berry-13) in [#14712](https://github.com/danny-avila/LibreChat/pull/14712) +- ๐Ÿงœ feat: Open Mermaid Diagrams as Artifacts with SVG/PNG Export by [@berry-13](https://github.com/berry-13) in [#14713](https://github.com/danny-avila/LibreChat/pull/14713) +- ๐Ÿชถ feat: Resolve Explicit Subagents Lazily by [@danny-avila](https://github.com/danny-avila) in [#14714](https://github.com/danny-avila/LibreChat/pull/14714) +- ๐Ÿ“ก feat: Route Web Search and Scrape Egress through the SSRF-safe Agent by [@dustinhealy](https://github.com/dustinhealy) in [#14606](https://github.com/danny-avila/LibreChat/pull/14606) +- ๐ŸŽจ feat: Add Versioned Theme Foundation by [@danny-avila](https://github.com/danny-avila) in [#14709](https://github.com/danny-avila/LibreChat/pull/14709) +- ๐Ÿช† feat: Add Parent Activity Phase Summaries by [@danny-avila](https://github.com/danny-avila) in [#14721](https://github.com/danny-avila/LibreChat/pull/14721) +- ๐ŸŽจ feat: Refine Client Colors and Sharing Dialogs by [@berry-13](https://github.com/berry-13) in [#14734](https://github.com/danny-avila/LibreChat/pull/14734) +- ๐ŸŽ›๏ธ feat: Adopt Composer Density Tokens by [@danny-avila](https://github.com/danny-avila) in [#14730](https://github.com/danny-avila/LibreChat/pull/14730) +- ๐Ÿก feat: Batched User Questions With A Single Bounded Answer Form by [@danny-avila](https://github.com/danny-avila) in [#14737](https://github.com/danny-avila/LibreChat/pull/14737) +- ๐Ÿช feat: Execute Agent Plugin Command Hooks by [@danny-avila](https://github.com/danny-avila) in [#14755](https://github.com/danny-avila/LibreChat/pull/14755) +- ๐Ÿšฃโ€โ™€๏ธ feat: Smooth Streaming Text Fade-In by [@danny-avila](https://github.com/danny-avila) in [#14757](https://github.com/danny-avila/LibreChat/pull/14757) +- ๐Ÿชข feat: add Langfuse session links by [@upman](https://github.com/upman) in [#14776](https://github.com/danny-avila/LibreChat/pull/14776) +- ๐Ÿ”– feat: Bound Parent Activity Phases With an Exclusive End Index by [@danny-avila](https://github.com/danny-avila) in [#14768](https://github.com/danny-avila/LibreChat/pull/14768) +- ๐Ÿ’ฌ style: Unify Message Row Layout and Edit Surfaces by [@berry-13](https://github.com/berry-13) in [#14770](https://github.com/danny-avila/LibreChat/pull/14770) +- ๐Ÿ“„ feat: accept PowerPoint template MIME type by [@snapydziuba](https://github.com/snapydziuba) in [#14761](https://github.com/danny-avila/LibreChat/pull/14761) +- โšก feat: Add Gemini 3.7 Flash Support by [@danny-avila](https://github.com/danny-avila) in [#14818](https://github.com/danny-avila/LibreChat/pull/14818) + +### ๐Ÿ› Fixes + +- ๐Ÿ”‘ fix: Honor User-Provided MCP API Key Instead of Forcing OAuth by [@danny-avila](https://github.com/danny-avila) in [#13954](https://github.com/danny-avila/LibreChat/pull/13954) +- ๐Ÿช™ fix: Count Quote Tokens on Message Edit by [@danny-avila](https://github.com/danny-avila) in [#13958](https://github.com/danny-avila/LibreChat/pull/13958) +- ๐Ÿ“‹ fix: Route Clipboard Paste Through Upload Options by [@dustinhealy](https://github.com/dustinhealy) in [#13957](https://github.com/danny-avila/LibreChat/pull/13957) +- ๐Ÿ“‡ fix: Index sharedlinks updatedAt for Cosmos DB Sorts by [@danny-avila](https://github.com/danny-avila) in [#13979](https://github.com/danny-avila/LibreChat/pull/13979) +- ๐Ÿ“‚ fix: Mount Skill Files Under skills/ in Code Interpreter by [@danny-avila](https://github.com/danny-avila) in [#13961](https://github.com/danny-avila/LibreChat/pull/13961) and [#13975](https://github.com/danny-avila/LibreChat/pull/13975) +- ๐ŸชŸ fix: Re-measure Sidebar Chat List on Width Change to Fix Date-Group Spacing by [@danny-avila](https://github.com/danny-avila) in [#13981](https://github.com/danny-avila/LibreChat/pull/13981) +- ๐Ÿ“ fix: Make create_file Missing-Content Error Truncation-Aware by [@danny-avila](https://github.com/danny-avila) in [#14043](https://github.com/danny-avila/LibreChat/pull/14043) +- fix: use `logAxiosError` at the RAG file_search/context call sites by [@mawburn](https://github.com/mawburn) in [#14014](https://github.com/danny-avila/LibreChat/pull/14014) +- fix: `stripHeavyErrorFields` Winston format (defense-in-depth) by [@mawburn](https://github.com/mawburn) in [#14018](https://github.com/danny-avila/LibreChat/pull/14018) +- ๐Ÿ“ฅ fix: Download Original File From Artifact Preview Panel for Office Documents by [@berry-13](https://github.com/berry-13) in [#14026](https://github.com/danny-avila/LibreChat/pull/14026) +- ๐Ÿ”ฅ fix: Firebase CDN Initialization Under tsdown CJS Interop by [@jakacenta](https://github.com/jakacenta) in [#14046](https://github.com/danny-avila/LibreChat/pull/14046) +- fix: preserve role SHARE permissions across boot in initializeRoles by [@mawburn](https://github.com/mawburn) in [#14022](https://github.com/danny-avila/LibreChat/pull/14022) +- fix: bound peak memory of concurrent base64 attachment encoding by [@mawburn](https://github.com/mawburn) in [#14023](https://github.com/danny-avila/LibreChat/pull/14023) +- ๐Ÿ“ง fix: Add .eml (message/rfc822) Support to File Upload by [@Zirkonium88](https://github.com/Zirkonium88) in [#13989](https://github.com/danny-avila/LibreChat/pull/13989) +- ๐Ÿšช fix: Support Admin Redirect Detection for Same-Origin Subpaths by [@arjunvijay24](https://github.com/arjunvijay24) in [#14040](https://github.com/danny-avila/LibreChat/pull/14040) +- ๐Ÿฉน fix: Coerce Stringified `edit_file` Edits (JSON-in-JSON) by [@danny-avila](https://github.com/danny-avila) in [#14056](https://github.com/danny-avila/LibreChat/pull/14056) +- ๐Ÿง  fix: Apply Bedrock thinking config to bare inference-profile model IDs by [@danny-avila](https://github.com/danny-avila) in [#14054](https://github.com/danny-avila/LibreChat/pull/14054) +- ๐Ÿง  fix: Default Bedrock thinking `maxTokens` to model max output by [@danny-avila](https://github.com/danny-avila) in [#14058](https://github.com/danny-avila/LibreChat/pull/14058) +- fix: stop the artifact-edit retry loop on unrecoverable 400s by [@mawburn](https://github.com/mawburn) in [#14060](https://github.com/danny-avila/LibreChat/pull/14060) +- ๐ŸŽฃ fix: Surface Resumable Stream Start Errors by [@danny-avila](https://github.com/danny-avila) in [#14072](https://github.com/danny-avila/LibreChat/pull/14072) +- ๐Ÿงฏ fix: Harden Principals Cache Invalidation and Lock-Wait Paths by [@danny-avila](https://github.com/danny-avila) in [#14120](https://github.com/danny-avila/LibreChat/pull/14120) +- ๐Ÿ fix: Ignore Finalized SSE Transport Errors by [@danny-avila](https://github.com/danny-avila) in [#14114](https://github.com/danny-avila/LibreChat/pull/14114) +- fix: fall back to `_id` for user id in `createSafeUser` by [@mawburn](https://github.com/mawburn) in [#14083](https://github.com/danny-avila/LibreChat/pull/14083) +- ๐ŸŒ fix: guard IME composition on Enter in prompt name/labels and dynamic tag inputs by [@mahirhir](https://github.com/mahirhir) in [#13996](https://github.com/danny-avila/LibreChat/pull/13996) +- ๐Ÿ—„๏ธ fix: Return Cached Transaction-Support Value on Cache Hit by [@Osamaali313](https://github.com/Osamaali313) in [#13999](https://github.com/danny-avila/LibreChat/pull/13999) +- ๐Ÿง  fix: Format Reasoning Exports by [@danny-avila](https://github.com/danny-avila) in [#14116](https://github.com/danny-avila/LibreChat/pull/14116) +- ๐Ÿงฎ fix: Prevent String Corruption of Numeric Agent Model Parameters by [@danny-avila](https://github.com/danny-avila) in [#14119](https://github.com/danny-avila/LibreChat/pull/14119) +- ๐Ÿงข fix: Raise Claude Sonnet 4.6 Output Cap by [@danny-avila](https://github.com/danny-avila) in [#14115](https://github.com/danny-avila/LibreChat/pull/14115) +- ๐Ÿงต fix: Preserve Fenced Markdown Artifacts by [@danny-avila](https://github.com/danny-avila) in [#14121](https://github.com/danny-avila/LibreChat/pull/14121) +- ๐Ÿ”’ fix: Prevent Role Grants on Shared Links by [@danny-avila](https://github.com/danny-avila) in [#14137](https://github.com/danny-avila/LibreChat/pull/14137) +- ๐Ÿค fix: Exclude Provider Secrets from HITL Pending Actions by [@danny-avila](https://github.com/danny-avila) in [#14136](https://github.com/danny-avila/LibreChat/pull/14136) +- โณ fix: Defer MCP Connection for Request-Scoped Placeholders on Reinitialize by [@danny-avila](https://github.com/danny-avila) in [#14148](https://github.com/danny-avila/LibreChat/pull/14148) +- ๐Ÿงท fix: Align Agent File Attachment Ownership by [@danny-avila](https://github.com/danny-avila) in [#14149](https://github.com/danny-avila/LibreChat/pull/14149) +- ๐ŸงŠ fix: Include Conversation Starters in Agent View and List Responses by [@serhiizghama](https://github.com/serhiizghama) in [#14142](https://github.com/danny-avila/LibreChat/pull/14142) +- โ™Š fix: Resolve Local JSON Pointer Refs & Sanitize Tool Search Schema for Gemini by [@usnavy13](https://github.com/usnavy13) in [#14161](https://github.com/danny-avila/LibreChat/pull/14161) +- ๐Ÿ›ก๏ธ fix: Guard HITL checkpoint size against MongoDB 16MB limit by [@danny-avila](https://github.com/danny-avila) in [#14157](https://github.com/danny-avila/LibreChat/pull/14157) +- ๐Ÿ”ก fix: Normalize Email Case When Issuing Verification Tokens by [@VictorEPlus](https://github.com/VictorEPlus) in [#14172](https://github.com/danny-avila/LibreChat/pull/14172) +- ๐Ÿชœ fix: Apply Recursion Limit Config to Subagents by [@danny-avila](https://github.com/danny-avila) in [#14185](https://github.com/danny-avila/LibreChat/pull/14185) +- ๐Ÿ’‚ fix: Enforce ALLOW_EMAIL_LOGIN on the Backend Login Route by [@lurkerCha](https://github.com/lurkerCha) in [#14180](https://github.com/danny-avila/LibreChat/pull/14180) +- ๐Ÿงฉ fix: Allow `compatibility` Field in Skill Frontmatter by [@danny-avila](https://github.com/danny-avila) in [#14189](https://github.com/danny-avila/LibreChat/pull/14189) +- ๐Ÿ“Ž fix: Translate Finite `supportedMimeTypes` Allowlists to Picker Accept by [@danny-avila](https://github.com/danny-avila) in [#14186](https://github.com/danny-avila/LibreChat/pull/14186) +- ๐Ÿช† fix: Serve Nested Skill Files Through a Wildcard Route by [@danny-avila](https://github.com/danny-avila) in [#14191](https://github.com/danny-avila/LibreChat/pull/14191) +- ๐Ÿƒ fix: Attach Request-Scoped MCP Servers From the Builder via the `mcp_all` Wildcard by [@adamscross04](https://github.com/adamscross04) in [#14177](https://github.com/danny-avila/LibreChat/pull/14177) +- ๐Ÿ” fix: Sync Conversation Title Updates to MeiliSearch by [@danny-avila](https://github.com/danny-avila) in [#14223](https://github.com/danny-avila/LibreChat/pull/14223) +- ๐Ÿ‘ป fix: Guard Redis Stream Resume Against Disposed HITL Graph by [@danny-avila](https://github.com/danny-avila) in [#14258](https://github.com/danny-avila/LibreChat/pull/14258) +- ๐Ÿค fix: Discover MCP OAuth Exchange Methods by [@danny-avila](https://github.com/danny-avila) in [#14256](https://github.com/danny-avila/LibreChat/pull/14256) +- ๐Ÿ‘‹ fix: Terminate Streamable HTTP MCP Sessions on Teardown by [@danny-avila](https://github.com/danny-avila) in [#14252](https://github.com/danny-avila/LibreChat/pull/14252) +- ๐Ÿ—‚๏ธ fix: Route read_file Through the Stateful Code Session by [@danny-avila](https://github.com/danny-avila) in [#14259](https://github.com/danny-avila/LibreChat/pull/14259) +- ๐Ÿ’ญ fix: Default GPT-5.6 Reasoning Requests to Responses API by [@jomspk](https://github.com/jomspk) in [#14232](https://github.com/danny-avila/LibreChat/pull/14232) +- ๐Ÿ”– fix: Preserve Ephemeral Agent Params and Identity for ask_user_question Resume by [@jjhidalgar-celonis](https://github.com/jjhidalgar-celonis) in [#14254](https://github.com/danny-avila/LibreChat/pull/14254) +- ๐ŸŽซ fix: Strip Reserved Fields From Bedrock `additionalModelRequestFields` by [@danny-avila](https://github.com/danny-avila) in [#14246](https://github.com/danny-avila/LibreChat/pull/14246) +- ๐Ÿ“ฑ fix: Single-Tap Select for Pinned Agents, Model Specs & Models on Touch by [@danny-avila](https://github.com/danny-avila) in [#14272](https://github.com/danny-avila/LibreChat/pull/14272) +- ๐Ÿงฝ fix: Clear Deleted Chats From Message Cache by [@danny-avila](https://github.com/danny-avila) in [#14270](https://github.com/danny-avila/LibreChat/pull/14270) +- ๐ŸงŸ fix: Prevent Drained Steer From Re-Queuing After Run-End Race by [@danny-avila](https://github.com/danny-avila) in [#14276](https://github.com/danny-avila/LibreChat/pull/14276) +- ๐Ÿ™‹ fix: Await `ask_user_question` Tool Factory in `loadTools` by [@danny-avila](https://github.com/danny-avila) in [#14291](https://github.com/danny-avila/LibreChat/pull/14291) +- ๐Ÿงท fix: Flush Pending File Deletion on Unmount by [@danny-avila](https://github.com/danny-avila) in [#14293](https://github.com/danny-avila/LibreChat/pull/14293) +- ๐Ÿ™‹ fix: Stop Answered `ask_user_question` Card From Reopening Its Popover by [@danny-avila](https://github.com/danny-avila) in [#14297](https://github.com/danny-avila/LibreChat/pull/14297) +- ๐Ÿ”’ fix: Scope, Cap, and De-Execute the In-Flight Steer Stack by [@danny-avila](https://github.com/danny-avila) in [#14310](https://github.com/danny-avila/LibreChat/pull/14310) +- ๐Ÿ“ฑ fix: Don't Connect the Favorites Drag Source on Touch Pointers by [@danny-avila](https://github.com/danny-avila) in [#14312](https://github.com/danny-avila/LibreChat/pull/14312) +- ๐Ÿงต fix: Harden Request-Scoped MCP Lifecycle by [@danny-avila](https://github.com/danny-avila) in [#14342](https://github.com/danny-avila/LibreChat/pull/14342) +- ๐Ÿช† fix: Build RAG-API Chart Before Parent to Bundle PostgreSQL Dependency by [@Aho-Bakaa](https://github.com/Aho-Bakaa) in [#14262](https://github.com/danny-avila/LibreChat/pull/14262) +- ๐Ÿšช fix: Keep Owners From Being Locked Out of Their Own Resource When Sharing by [@danny-avila](https://github.com/danny-avila) in [#14347](https://github.com/danny-avila/LibreChat/pull/14347) +- ๐Ÿš fix: Route Admin-Configured Document Types to RAG /text on Agent Upload by [@danny-avila](https://github.com/danny-avila) in [#14345](https://github.com/danny-avila/LibreChat/pull/14345) +- ๐ŸŽŸ๏ธ fix: Claim Idempotency Keys to Dedup Retried Generation Requests and Prevent Double Billing by [@danny-avila](https://github.com/danny-avila) in [#14344](https://github.com/danny-avila/LibreChat/pull/14344) +- ๐Ÿง  fix: Restore Agent Memory Scope Control in Unified Builder by [@danny-avila](https://github.com/danny-avila) in [#14292](https://github.com/danny-avila/LibreChat/pull/14292) +- ๐Ÿ›Ÿ fix: Keep File Uploads Alive With SSE Heartbeats by [@MarcAmick](https://github.com/MarcAmick) in [#14295](https://github.com/danny-avila/LibreChat/pull/14295) +- ๐Ÿงฉ fix: Preserve Deployment Skill IDs on Agents by [@danny-avila](https://github.com/danny-avila) in [#14368](https://github.com/danny-avila/LibreChat/pull/14368) +- ๐Ÿงญ fix: Keep Message Nav Chevrons Working on In-Thread Steers by [@danny-avila](https://github.com/danny-avila) in [#14377](https://github.com/danny-avila/LibreChat/pull/14377) +- ๐Ÿค fix: Withhold MCP OAuth Headers From Untrusted Preconfigured Discovery by [@danny-avila](https://github.com/danny-avila) in [#14379](https://github.com/danny-avila/LibreChat/pull/14379) +- ๐Ÿ”— fix: Preserve resource owner access when sharing (key share diff by stable id) by [@jomspk](https://github.com/jomspk) in [#14317](https://github.com/danny-avila/LibreChat/pull/14317) +- ๐Ÿช† fix: Preserve Nested Subagent Delegation by [@danny-avila](https://github.com/danny-avila) in [#14392](https://github.com/danny-avila/LibreChat/pull/14392) +- โœ‹ fix: Enable Submit on First Tool-Approval Decision by [@danny-avila](https://github.com/danny-avila) in [#14393](https://github.com/danny-avila/LibreChat/pull/14393) +- ๐ŸŽž๏ธ fix: Surface Clear Error for Unprocessable Gemini YouTube Videos by [@danny-avila](https://github.com/danny-avila) in [#14396](https://github.com/danny-avila/LibreChat/pull/14396) +- ๐Ÿ“Œ fix: Pin Scroll-to-Bottom Rib in Message Nav by [@danny-avila](https://github.com/danny-avila) in [#14397](https://github.com/danny-avila/LibreChat/pull/14397) +- ๐Ÿซ™ fix: Preserve Loaded Message Content When Resume Snapshot Is Empty by [@danny-avila](https://github.com/danny-avila) in [#14399](https://github.com/danny-avila/LibreChat/pull/14399) +- ๐ŸŽฏ fix: Correct Off-by-One Rail Scrub After Pinning the Terminus by [@danny-avila](https://github.com/danny-avila) in [#14409](https://github.com/danny-avila/LibreChat/pull/14409) +- โ™พ๏ธ fix: Preserve Resumable Stream Ordering Across Turns by [@danny-avila](https://github.com/danny-avila) in [#14411](https://github.com/danny-avila/LibreChat/pull/14411) +- ๐Ÿงฉ fix: Harden Agent Skill Lifecycles End to End by [@danny-avila](https://github.com/danny-avila) in [#14429](https://github.com/danny-avila/LibreChat/pull/14429) +- ๐Ÿ“ง fix: Restore `invite-user` CLI by [@unsnow-iac](https://github.com/unsnow-iac) in [#14436](https://github.com/danny-avila/LibreChat/pull/14436) +- ๐Ÿ”— fix: Resolve MCP Tool-Key Boundary Against Configured Server Names by [@danny-avila](https://github.com/danny-avila) in [#14448](https://github.com/danny-avila/LibreChat/pull/14448) +- ๐Ÿƒ fix: Strip $-Prefixed Schema Keywords Before Persisting MCP Tool Params by [@danny-avila](https://github.com/danny-avila) in [#14464](https://github.com/danny-avila/LibreChat/pull/14464) +- ๐Ÿ”— fix: Render Shared Links Containing Steers by [@danny-avila](https://github.com/danny-avila) in [#14480](https://github.com/danny-avila/LibreChat/pull/14480) +- ๐Ÿ”’ fix: Bound `/files/usage` TTL Hold Instead of Clearing It by [@danny-avila](https://github.com/danny-avila) in [#14470](https://github.com/danny-avila/LibreChat/pull/14470) +- ๐Ÿค fix: Filter Admin Config Reads by Section-Scoped Read Capability by [@dustinhealy](https://github.com/dustinhealy) in [#14472](https://github.com/danny-avila/LibreChat/pull/14472) +- ๐Ÿƒ fix: Amazon DocumentDB Compatibility for Pipeline-Form Updates by [@danny-avila](https://github.com/danny-avila) in [#14495](https://github.com/danny-avila/LibreChat/pull/14495) +- ๐Ÿ›ก๏ธ fix: validate message feedback payloads by [@upman](https://github.com/upman) in [#14500](https://github.com/danny-avila/LibreChat/pull/14500) +- ๐Ÿงฉ fix: Apply Every Entry of Multi-Part Stream Deltas by [@danny-avila](https://github.com/danny-avila) in [#14502](https://github.com/danny-avila/LibreChat/pull/14502) +- ๐Ÿท๏ธ fix: Re-attribute Agent Content After In-Thread Steers by [@danny-avila](https://github.com/danny-avila) in [#14497](https://github.com/danny-avila/LibreChat/pull/14497) +- ๐ŸŽฏ fix: Keep Run Steps and Labels in One Index Space After a Resume Sync by [@danny-avila](https://github.com/danny-avila) in [#14516](https://github.com/danny-avila/LibreChat/pull/14516) +- ๐Ÿชถ fix: Yield Soft Default Model Spec to Agent Picks in Picker-Only Deployments by [@danny-avila](https://github.com/danny-avila) in [#14515](https://github.com/danny-avila/LibreChat/pull/14515) +- ๐ŸชŸ fix: Surface MCP Initialization Errors by [@danny-avila](https://github.com/danny-avila) in [#14529](https://github.com/danny-avila/LibreChat/pull/14529) +- ๐Ÿชƒ fix: Resolve User Vars Before the First Post-OAuth Reconnect by [@schumajs](https://github.com/schumajs) in [#14538](https://github.com/danny-avila/LibreChat/pull/14538) +- ๐Ÿ”’ fix: Remove Owner Email from Agent `owner_contact` Fallback by [@danny-avila](https://github.com/danny-avila) in [#14541](https://github.com/danny-avila/LibreChat/pull/14541) +- ๐Ÿ“„ fix: Filter Non-PDF Documents on the Anthropic Encode Path by [@danny-avila](https://github.com/danny-avila) in [#14535](https://github.com/danny-avila/LibreChat/pull/14535) +- ๐ŸŽฏ fix: Exact Ask-Question Attribution via Interrupt tool_call_id by [@danny-avila](https://github.com/danny-avila) in [#14539](https://github.com/danny-avila/LibreChat/pull/14539) +- ๐Ÿงน fix: Clean Up MCP OAuth State Mappings on Uninstall + Reject Superseded Callbacks by [@danny-avila](https://github.com/danny-avila) in [#14549](https://github.com/danny-avila/LibreChat/pull/14549) +- ๐Ÿง  fix: Preserve Deferred Tool Schemas Across HITL Resume by [@danny-avila](https://github.com/danny-avila) in [#14552](https://github.com/danny-avila/LibreChat/pull/14552) +- ๐Ÿฆ— fix: Ignore Sequenced Redis Events Without SSE Subscribers by [@danny-avila](https://github.com/danny-avila) in [#14557](https://github.com/danny-avila/LibreChat/pull/14557) +- ๐Ÿ”— fix: Normalize MCP Tool Keys at Every Producer, Resolve Raw Names via Aliases by [@danny-avila](https://github.com/danny-avila) in [#14553](https://github.com/danny-avila/LibreChat/pull/14553) +- ๐Ÿข fix: Preserve Tenant Context for Partial Response Saves on Disconnect by [@danny-avila](https://github.com/danny-avila) in [#14567](https://github.com/danny-avila/LibreChat/pull/14567) +- ๐Ÿฆ— fix: Deliver Abort Acknowledgements on Zero-Subscriber Replicas by [@danny-avila](https://github.com/danny-avila) in [#14569](https://github.com/danny-avila/LibreChat/pull/14569) +- ๐Ÿท๏ธ fix: Skip Title Generation for Preempt-Incomplete Turns by [@danny-avila](https://github.com/danny-avila) in [#14571](https://github.com/danny-avila/LibreChat/pull/14571) +- ๐Ÿชง fix: Guard Admin OAuth Routes When Providers Are Not Configured by [@cyphercodes](https://github.com/cyphercodes) in [#14507](https://github.com/danny-avila/LibreChat/pull/14507) +- ๐Ÿ”— fix: Resolve Relative Skill Markdown Links by [@berry-13](https://github.com/berry-13) in [#14586](https://github.com/danny-avila/LibreChat/pull/14586) +- ๐Ÿงญ fix: Drop v6-Only MemoryRouter future Prop from Skill Markdown Spec by [@danny-avila](https://github.com/danny-avila) in [#14588](https://github.com/danny-avila/LibreChat/pull/14588) +- ๐Ÿชช fix: Strip Unresolved Header Placeholders at Final Resolution by [@danny-avila](https://github.com/danny-avila) in [#14595](https://github.com/danny-avila/LibreChat/pull/14595) +- ๐Ÿ”’ fix: Single-Flight MCP OAuth Token Refresh per User/Server by [@danny-avila](https://github.com/danny-avila) in [#14596](https://github.com/danny-avila/LibreChat/pull/14596) +- ๐Ÿชบ fix: Keep Preempt-Abandoned Siblings Nested, Make Message Tree Order-Robust by [@danny-avila](https://github.com/danny-avila) in [#14587](https://github.com/danny-avila/LibreChat/pull/14587) +- โŒจ๏ธ fix: Honor `defaultPrevented` in Global Shortcut Dispatch by [@danny-avila](https://github.com/danny-avila) in [#14570](https://github.com/danny-avila/LibreChat/pull/14570) +- ๐Ÿชข fix: Bind MCP OAuth Secrets to Trusted Endpoints by [@danny-avila](https://github.com/danny-avila) in [#14578](https://github.com/danny-avila/LibreChat/pull/14578) +- โš“ fix: Bind Action Servers to Metadata Ports by [@danny-avila](https://github.com/danny-avila) in [#14575](https://github.com/danny-avila/LibreChat/pull/14575) +- ๐Ÿงฑ fix: Enforce Agent Runtime File Trust Boundaries by [@danny-avila](https://github.com/danny-avila) in [#14577](https://github.com/danny-avila/LibreChat/pull/14577) +- ๐Ÿ“ fix: Scope Skill Command Query to Text Before the Caret by [@danny-avila](https://github.com/danny-avila) in [#14604](https://github.com/danny-avila/LibreChat/pull/14604) +- ๐Ÿงฌ fix: Resolve URL-Named Model Spec to Its Full Preset on Cold Load by [@danny-avila](https://github.com/danny-avila) in [#14610](https://github.com/danny-avila/LibreChat/pull/14610) +- โœ‚๏ธ fix: Truncate Overflowing Activity and Intent Labels in Chat UI by [@danny-avila](https://github.com/danny-avila) in [#14607](https://github.com/danny-avila/LibreChat/pull/14607) +- ๐Ÿšฆ fix: Bound, Single-Flight, and Retry Skill File Priming Uploads by [@danny-avila](https://github.com/danny-avila) in [#14611](https://github.com/danny-avila/LibreChat/pull/14611) +- ๐Ÿงน fix: Exclude Mongo ID From Conversation Updates by [@danny-avila](https://github.com/danny-avila) in [#14631](https://github.com/danny-avila/LibreChat/pull/14631) +- โ™ฟ๏ธ a11y: improve keyboard operability, focus retention, and accessible naming by [@berry-13](https://github.com/berry-13) in [#14600](https://github.com/danny-avila/LibreChat/pull/14600) +- ๐Ÿš fix: Localized Guidance for Model-Not-Found Errors by [@danny-avila](https://github.com/danny-avila) in [`557c22d102`](https://github.com/danny-avila/LibreChat/commit/557c22d10240a66a068584f1098c54a436c4dcc8) +- ๐Ÿ›ก๏ธ fix: Run message-filter PII patterns on a linear-time regex engine (ReDoS) by [@dustinhealy](https://github.com/dustinhealy) in [#14554](https://github.com/danny-avila/LibreChat/pull/14554) +- ๐Ÿชข fix: disable central fanout media uploads for langfuse by [@upman](https://github.com/upman) in [#14642](https://github.com/danny-avila/LibreChat/pull/14642) +- ๐Ÿงญ fix: Fail Closed When Expected MCP Tools Are Unavailable by [@danny-avila](https://github.com/danny-avila) in [#14646](https://github.com/danny-avila/LibreChat/pull/14646) +- ๐Ÿ›‚ fix: Honor Claude Document Limits Through Inference Gateways by [@danny-avila](https://github.com/danny-avila) in [#14650](https://github.com/danny-avila/LibreChat/pull/14650) +- ๐ŸŽŸ๏ธ fix: Reconcile MCP OAuth Readiness Across Pods by [@danny-avila](https://github.com/danny-avila) in [#14629](https://github.com/danny-avila/LibreChat/pull/14629) +- ๐ŸŒŠ fix: Preserve Custom Endpoint `streamRate` When `endpoints.all` Is Defined by [@danny-avila](https://github.com/danny-avila) in [#14645](https://github.com/danny-avila/LibreChat/pull/14645) +- ๐Ÿ” fix: Preserve Structured JWT Auth Context by [@danny-avila](https://github.com/danny-avila) in [#14652](https://github.com/danny-avila/LibreChat/pull/14652) +- โฑ๏ธ fix: Compile admin file-config MIME patterns on a linear-time engine (ReDoS) by [@dustinhealy](https://github.com/dustinhealy) in [#14555](https://github.com/danny-avila/LibreChat/pull/14555) +- ๐Ÿ›ก๏ธ fix: SSRF-Guard Speech (STT/TTS) and OCR Outbound Requests at Connect Time by [@dustinhealy](https://github.com/dustinhealy) in [#14560](https://github.com/danny-avila/LibreChat/pull/14560) +- ๐Ÿ” fix: Re-Arm Soft Default When a Stored Agent No Longer Resolves by [@danny-avila](https://github.com/danny-avila) in [#14664](https://github.com/danny-avila/LibreChat/pull/14664) +- ๐Ÿ”— fix: Prevent duplicate share rows from clobbering pending role edits (dedupe adds by stable id) by [@jomspk](https://github.com/jomspk) in [#14655](https://github.com/danny-avila/LibreChat/pull/14655) +- ๐Ÿ›Ÿ fix: Stop Agents When Code Resources Cannot Recover by [@danny-avila](https://github.com/danny-avila) in [#14651](https://github.com/danny-avila/LibreChat/pull/14651) +- โ™ฟ fix: Restore WCAG AA Contrast for Text Tokens & Hide Edit Action While Streaming by [@danny-avila](https://github.com/danny-avila) in [#14677](https://github.com/danny-avila/LibreChat/pull/14677) +- ๐Ÿฉน fix: Keep Edit Action Fully Hidden While Streaming by [@danny-avila](https://github.com/danny-avila) in [#14687](https://github.com/danny-avila/LibreChat/pull/14687) +- ๐Ÿ“ก fix: Refresh MCP Tools After List-Changed Notifications by [@danny-avila](https://github.com/danny-avila) in [#14686](https://github.com/danny-avila/LibreChat/pull/14686) +- ๐Ÿงฌ fix: Rebind Request Context After Remote Agent Auth by [@danny-avila](https://github.com/danny-avila) in [#14685](https://github.com/danny-avila/LibreChat/pull/14685) +- ๐Ÿงญ fix: Make MCP Catalog Redis Cluster-Safe by [@danny-avila](https://github.com/danny-avila) in [#14717](https://github.com/danny-avila/LibreChat/pull/14717) +- ๐Ÿงฌ fix: Normalize Legacy MCP Null Headers by [@danny-avila](https://github.com/danny-avila) in [#14720](https://github.com/danny-avila/LibreChat/pull/14720) +- ๐Ÿ“ fix: Consistent Export Filenames Across Formats by [@lidonius1122](https://github.com/lidonius1122) in [#14708](https://github.com/danny-avila/LibreChat/pull/14708) +- ๐Ÿงท fix: Safely Recover Runtime MCP OAuth Rejections by [@danny-avila](https://github.com/danny-avila) in [#14684](https://github.com/danny-avila/LibreChat/pull/14684) +- ๐Ÿช† fix: Rebase Activity Phase Bounds over Sparse Content by [@danny-avila](https://github.com/danny-avila) in [#14729](https://github.com/danny-avila/LibreChat/pull/14729) +- ๐Ÿ“Ž fix: Re-enable Send After File Upload by [@danny-avila](https://github.com/danny-avila) in [#14727](https://github.com/danny-avila/LibreChat/pull/14727) +- ๐Ÿ“ธ fix: Guard Screenshot Export Against Main-Thread Freezes by [@danny-avila](https://github.com/danny-avila) in [#14733](https://github.com/danny-avila/LibreChat/pull/14733) +- ๐Ÿ” fix: Preserve Plugin MCP Provenance Through Registry Storage by [@danny-avila](https://github.com/danny-avila) in [#14744](https://github.com/danny-avila/LibreChat/pull/14744) +- ๐Ÿงญ fix: Re-Anchor Parent Activity Phase Bounds by [@danny-avila](https://github.com/danny-avila) in [#14741](https://github.com/danny-avila/LibreChat/pull/14741) +- ๐Ÿงท fix: Preserve Elicitation Answers Across Aborts by [@danny-avila](https://github.com/danny-avila) in [#14745](https://github.com/danny-avila/LibreChat/pull/14745) +- ๐Ÿ“ก fix: Preserve Redis Abort Terminal Delivery by [@danny-avila](https://github.com/danny-avila) in [#14749](https://github.com/danny-avila/LibreChat/pull/14749) +- โŒจ๏ธ fix: allow file upload shortcut when editing by [@likeabas](https://github.com/likeabas) in [#14764](https://github.com/danny-avila/LibreChat/pull/14764) +- ๐Ÿ›Ÿ fix: Isolate Invalid Skills During GitHub Sync by [@berry-13](https://github.com/berry-13) in [#14735](https://github.com/danny-avila/LibreChat/pull/14735) +- ๐ŸŽ™๏ธ fix: Align Speech Engine Configuration With Runtime by [@berry-13](https://github.com/berry-13) in [#14736](https://github.com/danny-avila/LibreChat/pull/14736) +- ๐Ÿงฉ fix: Normalize Malformed MCP Required Schemas by [@danny-avila](https://github.com/danny-avila) in [#14771](https://github.com/danny-avila/LibreChat/pull/14771) +- ๐Ÿงพ fix: Honor Disabled Transactions on the Token-Count Fallback Path by [@jtodaroii](https://github.com/jtodaroii) in [#14774](https://github.com/danny-avila/LibreChat/pull/14774) +- ๐Ÿ›ฐ๏ธ fix: Attach Request-Scoped MCP Servers by [@danny-avila](https://github.com/danny-avila) in [#14780](https://github.com/danny-avila/LibreChat/pull/14780) +- ๐Ÿ“ฑ fix: Show Quote Popup for Block Selections and on Touch Devices by [@danny-avila](https://github.com/danny-avila) in [#14777](https://github.com/danny-avila/LibreChat/pull/14777) +- ๐Ÿช‘ fix: Rebase Activity Phase Bounds Onto Compacted Content and Unskip the MCPManager Suite by [@danny-avila](https://github.com/danny-avila) in [#14782](https://github.com/danny-avila/LibreChat/pull/14782) +- ๐Ÿ”– fix: Split Activity Phases at Substantial Text by [@danny-avila](https://github.com/danny-avila) in [#14785](https://github.com/danny-avila/LibreChat/pull/14785) +- ๐Ÿ–Œ๏ธ style: Use correct text colour for answer textarea in dark mode by [@lizzykerrigan](https://github.com/lizzykerrigan) in [#14791](https://github.com/danny-avila/LibreChat/pull/14791) +- ๐Ÿฉน fix: Restore the `@librechat/api` Build and Remove Legacy Code by [@danny-avila](https://github.com/danny-avila) in [#14808](https://github.com/danny-avila/LibreChat/pull/14808) +- ๐Ÿฉน fix: apply agent updates that match the newest version entry by [@mihidumh](https://github.com/mihidumh) in [#14810](https://github.com/danny-avila/LibreChat/pull/14810) +- ๐Ÿ’ฌ style: Right-Align In-Flight Steer Bubbles to the Message UI by [@danny-avila](https://github.com/danny-avila) in [#14814](https://github.com/danny-avila/LibreChat/pull/14814) +- ๐Ÿ”Œ fix: Preserve MCP `serverInstructions` Declaration Through Inspection by [@danny-avila](https://github.com/danny-avila) in [#14815](https://github.com/danny-avila/LibreChat/pull/14815) +- ๐Ÿ”Œ fix: Recover Quietly From Stale MCP SSE Stream Conflicts by [@danny-avila](https://github.com/danny-avila) in [#14816](https://github.com/danny-avila/LibreChat/pull/14816) +- ๐Ÿ“Ž fix: Alias Shell Script MIME Variants to `application/x-sh` by [@danny-avila](https://github.com/danny-avila) in [#14817](https://github.com/danny-avila/LibreChat/pull/14817) + +### ๐Ÿ”ง Refactoring and Performance + +- โ™ป๏ธ refactor: Compute Context Gauge Client-Side, Drop Projection Endpoint by [@danny-avila](https://github.com/danny-avila) in [#13953](https://github.com/danny-avila/LibreChat/pull/13953) +- ๐Ÿชฃ refactor: Rate-Limit Token Routes and Cap Remote File Downloads by [@danny-avila](https://github.com/danny-avila) in [#13978](https://github.com/danny-avila/LibreChat/pull/13978) +- ๐Ÿฆฅ perf: Lazy-Load Agent Version History in Editor by [@danny-avila](https://github.com/danny-avila) in [#13977](https://github.com/danny-avila/LibreChat/pull/13977) +- ๐Ÿ›— perf: Fetch Pinned Agents Directly Past the Global Agents Map by [@danny-avila](https://github.com/danny-avila) in [#13972](https://github.com/danny-avila/LibreChat/pull/13972) +- โšก perf: memoize FavoritesList and BookmarkNav to prevent re-renders during streaming by [@berry-13](https://github.com/berry-13) in [#14011](https://github.com/danny-avila/LibreChat/pull/14011) +- ๐Ÿ—บ๏ธ refactor: Light Up In-Viewport Ribs at Rest in Message Nav by [@danny-avila](https://github.com/danny-avila) in [#14041](https://github.com/danny-avila/LibreChat/pull/14041) +- โšก perf: Minimize group membership query in principal resolution by [@danny-avila](https://github.com/danny-avila) in [#14055](https://github.com/danny-avila/LibreChat/pull/14055) +- โšก perf: Skip Role Route Capability Probe for Own and Default Roles by [@danny-avila](https://github.com/danny-avila) in [#14073](https://github.com/danny-avila/LibreChat/pull/14073) +- ๐Ÿชญ refactor: safe structured failure logging for langfuse fanout gateway by [@upman](https://github.com/upman) in [#14050](https://github.com/danny-avila/LibreChat/pull/14050) +- ๐Ÿ“‰ perf: Skip Redundant Permission Queries on MCP Servers List by [@danny-avila](https://github.com/danny-avila) in [#14077](https://github.com/danny-avila/LibreChat/pull/14077) +- โšก perf: Persist HITL checkpoints only on pause (lazy checkpointer) by [@danny-avila](https://github.com/danny-avila) in [#14024](https://github.com/danny-avila/LibreChat/pull/14024) +- ๐Ÿ—ƒ๏ธ perf: Cache Group Memberships for ACL Principal Resolution by [@danny-avila](https://github.com/danny-avila) in [#14075](https://github.com/danny-avila/LibreChat/pull/14075) +- โš™๏ธ perf: reduce first-load MongoDB round trips by [@upman](https://github.com/upman) in [#14101](https://github.com/danny-avila/LibreChat/pull/14101) +- ๐ŸŽฏ style: Center Scroll-to-Bottom Rib in Message Nav Rail by [@danny-avila](https://github.com/danny-avila) in [#14151](https://github.com/danny-avila/LibreChat/pull/14151) +- ๐Ÿ“‰ perf: cache OpenID JWT user documents by [@upman](https://github.com/upman) in [#14187](https://github.com/danny-avila/LibreChat/pull/14187) +- ๐Ÿ“‰ perf: start message queries before file map loads by [@upman](https://github.com/upman) in [#14188](https://github.com/danny-avila/LibreChat/pull/14188) +- ๐Ÿชœ style: Adjust rib dimensions and button sizes in `MessageNav` by [@danny-avila](https://github.com/danny-avila) in [#14234](https://github.com/danny-avila/LibreChat/pull/14234) +- ๐Ÿชœ style: Center scroll-to-bottom marker in MessageNav by [@danny-avila](https://github.com/danny-avila) in [#14238](https://github.com/danny-avila/LibreChat/pull/14238) +- ๐Ÿ›ž style: Reveal the Steered "?" on Message Hover/Focus by [@danny-avila](https://github.com/danny-avila) in [#14271](https://github.com/danny-avila/LibreChat/pull/14271) +- ๐Ÿ™Š refactor: Clarify Ask Question Schema Errors and Retry Guidance by [@danny-avila](https://github.com/danny-avila) in [#14279](https://github.com/danny-avila/LibreChat/pull/14279) +- ๐Ÿ’ฌ refactor: Anchor In-Flight Steers Above the Composer by [@danny-avila](https://github.com/danny-avila) in [#14308](https://github.com/danny-avila/LibreChat/pull/14308) +- โšก perf: Halve Per-Delta Redis Round Trips in Resumable Streams by [@danny-avila](https://github.com/danny-avila) in [#14313](https://github.com/danny-avila/LibreChat/pull/14313) +- ๐Ÿงญ refactor: `web_search` Description on When To Search vs Answer Directly by [@joshbla](https://github.com/joshbla) in [#13930](https://github.com/danny-avila/LibreChat/pull/13930) +- ๐Ÿงท perf: Stabilize Mutation-Dependent Memos in Chat Hooks by [@danny-avila](https://github.com/danny-avila) in [#14328](https://github.com/danny-avila/LibreChat/pull/14328) +- ๐Ÿšฐ perf: Suppress No-Op Conversation Writes and Widen-Proof Atom Subscriptions by [@danny-avila](https://github.com/danny-avila) in [#14329](https://github.com/danny-avila/LibreChat/pull/14329) +- ๐Ÿ” refactor: Surface primary OpenID JWT failure reason in auth failure log by [@danny-avila](https://github.com/danny-avila) in [#14346](https://github.com/danny-avila/LibreChat/pull/14346) +- ๐Ÿงญ perf: Warm Conversation Switches with Single-Navigation Focus Intent by [@danny-avila](https://github.com/danny-avila) in [#14334](https://github.com/danny-avila/LibreChat/pull/14334) +- ๐Ÿงน perf: Share Voices Store, Gate Timestamp Ticker, Stabilize Greeting Springs by [@danny-avila](https://github.com/danny-avila) in [#14335](https://github.com/danny-avila/LibreChat/pull/14335) +- ๐ŸŽž๏ธ perf: Coalesce Streaming Delta Cache Writes Per Animation Frame by [@danny-avila](https://github.com/danny-avila) in [#14332](https://github.com/danny-avila/LibreChat/pull/14332) +- ๐ŸŽ›๏ธ perf: Narrow Composer Subscriptions to Streaming State by [@danny-avila](https://github.com/danny-avila) in [#14333](https://github.com/danny-avila/LibreChat/pull/14333) +- ๐Ÿงฌ perf: Memoize Message Spine and Isolate Scroll-Button State by [@danny-avila](https://github.com/danny-avila) in [#14330](https://github.com/danny-avila/LibreChat/pull/14330) +- ๐ŸชŸ perf: Virtualize Search Results and Stop the Per-Query Remount by [@danny-avila](https://github.com/danny-avila) in [#14352](https://github.com/danny-avila/LibreChat/pull/14352) +- โšก perf: Reduce Agent Chat Startup Latency by [@danny-avila](https://github.com/danny-avila) in [#14423](https://github.com/danny-avila/LibreChat/pull/14423) +- ๐Ÿ’ฌ refactor: Raise `ask_user_question` Option Label Cap to 280 Chars by [@danny-avila](https://github.com/danny-avila) in [#14491](https://github.com/danny-avila/LibreChat/pull/14491) +- ๐Ÿชข refactor: Move Agent Execution Seam Before Initialization by [@danny-avila](https://github.com/danny-avila) in [#14581](https://github.com/danny-avila/LibreChat/pull/14581) +- ๐Ÿ“‰ perf: Bound Early Event Buffering for Detached Generations by [@danny-avila](https://github.com/danny-avila) in [#14612](https://github.com/danny-avila/LibreChat/pull/14612) +- ๐ŸŽจ refactor: adopt the `@librechat/client` design system (semantic color tokens + component migration) by [@berry-13](https://github.com/berry-13) in [#13879](https://github.com/danny-avila/LibreChat/pull/13879) +- ๐Ÿงฉ refactor: Shared UI Design System Tokens by [@danny-avila](https://github.com/danny-avila) in [#14670](https://github.com/danny-avila/LibreChat/pull/14670) +- โšก perf: Agent List and Model Selector at Scale by [@berry-13](https://github.com/berry-13) in [#14601](https://github.com/danny-avila/LibreChat/pull/14601) +- ๐Ÿงญ refactor: make the side panels behave the same way by [@berry-13](https://github.com/berry-13) in [#14695](https://github.com/danny-avila/LibreChat/pull/14695) +- ๐Ÿซง refactor: Fading Pre-Response Dot, Legacy Cursor CSS Removed by [@danny-avila](https://github.com/danny-avila) in [#14772](https://github.com/danny-avila/LibreChat/pull/14772) +- ๐Ÿงฑ refactor: Require Broad Config Management for Base Field Mutations by [@danny-avila](https://github.com/danny-avila) in [#14775](https://github.com/danny-avila/LibreChat/pull/14775) +- ๐Ÿ–๏ธ refactor: Typed Console Colors and Hardened Script Helpers by [@danny-avila](https://github.com/danny-avila) in [#14778](https://github.com/danny-avila/LibreChat/pull/14778) +- ๐Ÿงฑ refactor: Make Activity Phase Anchor Construction Exhaustive by [@danny-avila](https://github.com/danny-avila) in [#14805](https://github.com/danny-avila/LibreChat/pull/14805) +- ๐Ÿงญ refactor: Resolve Activity Phase Position Once Per Boundary by [@danny-avila](https://github.com/danny-avila) in [#14807](https://github.com/danny-avila/LibreChat/pull/14807) + +### ๐Ÿงช Tests + +- ๐Ÿ“ test: Guard Web Search Description Length by [@danny-avila](https://github.com/danny-avila) in [#14044](https://github.com/danny-avila/LibreChat/pull/14044) +- ๐Ÿ›‚ test: Cover Tool Approval Workflows End to End by [@danny-avila](https://github.com/danny-avila) in [#14427](https://github.com/danny-avila/LibreChat/pull/14427) +- ๐Ÿงญ test: Cover Agent Handoffs End to End by [@danny-avila](https://github.com/danny-avila) in [#14428](https://github.com/danny-avila/LibreChat/pull/14428) +- ๐Ÿงช test: Reasoning-Stream Render Perf Benchmark via react-scan by [@danny-avila](https://github.com/danny-avila) in [#14494](https://github.com/danny-avila/LibreChat/pull/14494) +- ๐ŸŽ›๏ธ test: Guard Multi-Steer Injection Across Tool Boundaries by [@danny-avila](https://github.com/danny-avila) in [#14498](https://github.com/danny-avila/LibreChat/pull/14498) +- ๐Ÿงช test: Run mock E2E against Redis in shards by [@danny-avila](https://github.com/danny-avila) in [#14551](https://github.com/danny-avila/LibreChat/pull/14551) +- ๐ŸŽฒ test: Replace Microtask Timing Assumptions in Client Specs by [@berry-13](https://github.com/berry-13) in [#14653](https://github.com/danny-avila/LibreChat/pull/14653) +- ๐Ÿ˜ test: refresh FerretDB harness, registry-derived models, bulkWrite coverage by [@danny-avila](https://github.com/danny-avila) in [#14679](https://github.com/danny-avila/LibreChat/pull/14679) +- test(mcp): mock static tool startup sync by [@danny-avila](https://github.com/danny-avila) in [#14711](https://github.com/danny-avila/LibreChat/pull/14711) +- ๐Ÿงช test(e2e): add Bombadil property exploration by [@upman](https://github.com/upman) in [#14462](https://github.com/danny-avila/LibreChat/pull/14462) +- ๐Ÿงพ test: Pin the Transactions Config Wiring on the Fallback Path by [@danny-avila](https://github.com/danny-avila) in [#14779](https://github.com/danny-avila/LibreChat/pull/14779) + +### ๐Ÿ“ฆ Dependencies, Chores & CI + +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.2.52 by [@danny-avila](https://github.com/danny-avila) in [#13939](https://github.com/danny-avila/LibreChat/pull/13939) +- โฌ†๏ธ chore: Migrate off deprecated @ariakit/react-core to @ariakit/react-components by [@danny-avila](https://github.com/danny-avila) in [#13940](https://github.com/danny-avila/LibreChat/pull/13940) +- ๐Ÿงช ci: Resolve DataTable test infinite re-render by [@danny-avila](https://github.com/danny-avila) in [#13947](https://github.com/danny-avila/LibreChat/pull/13947) +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.2.54 by [@danny-avila](https://github.com/danny-avila) in [#14035](https://github.com/danny-avila/LibreChat/pull/14035) +- ๐Ÿ”„ chore: Bump `@librechat/agents` to v3.2.55 by [@danny-avila](https://github.com/danny-avila) in [`954caef3a3`](https://github.com/danny-avila/LibreChat/commit/954caef3a35dabec2e5d5b56ae78ea5349c4721f) +- ๐Ÿงช ci: De-flake ConversationsSection Memoization Spec on Slow Runners by [@danny-avila](https://github.com/danny-avila) in [#14071](https://github.com/danny-avila/LibreChat/pull/14071) +- ๐Ÿงท chore: Expose Retain Recent Summarization Config by [@danny-avila](https://github.com/danny-avila) in [#14134](https://github.com/danny-avila/LibreChat/pull/14134) +- ๐Ÿ“ฆ chore: bump langfuse fanout Go dependencies by [@upman](https://github.com/upman) in [#14126](https://github.com/danny-avila/LibreChat/pull/14126) +- โญ docs: update Star History section by [@berry-13](https://github.com/berry-13) in [#14198](https://github.com/danny-avila/LibreChat/pull/14198) +- ๐Ÿ“ฆ chore: Update `@librechat/agents` to v3.2.62 by [@danny-avila](https://github.com/danny-avila) in [#14235](https://github.com/danny-avila/LibreChat/pull/14235) +- ๐Ÿ“ฆ chore: Update `@librechat/agents` to v3.2.65 by [@danny-avila](https://github.com/danny-avila) in [#14263](https://github.com/danny-avila/LibreChat/pull/14263) +- ๐Ÿงน chore: Prune Dangling Images After deployed-update Pull by [@danny-avila](https://github.com/danny-avila) in [#14269](https://github.com/danny-avila/LibreChat/pull/14269) +- ๐Ÿฝ๏ธ chore: Drop Pending Composer Draft When Steering or Queuing by [@danny-avila](https://github.com/danny-avila) in [#14289](https://github.com/danny-avila/LibreChat/pull/14289) +- ๐Ÿงฉ chore: Prebundle Node Polyfills for Buffer, Process, and Global in Vite `optimizeDeps` by [@danny-avila](https://github.com/danny-avila) in [#14354](https://github.com/danny-avila/LibreChat/pull/14354) +- ๐Ÿ“ฆ chore: Update `@librechat/agents` to v3.2.66 & `npm audit fix` by [@danny-avila](https://github.com/danny-avila) in [#14361](https://github.com/danny-avila/LibreChat/pull/14361) +- ๐Ÿงพ ci: Skip Workflows for Markdown-Only Changes by [@danny-avila](https://github.com/danny-avila) in [#14378](https://github.com/danny-avila/LibreChat/pull/14378) +- ๐Ÿ“ฆ chore: Update `@librechat/agents` to v3.2.68 by [@danny-avila](https://github.com/danny-avila) in [#14380](https://github.com/danny-avila/LibreChat/pull/14380) +- ๐Ÿšฆ ci: Gate Playwright Runs to Maintainers by [@danny-avila](https://github.com/danny-avila) in [#14385](https://github.com/danny-avila/LibreChat/pull/14385) +- ๐ŸŽญ ci: Scope Playwright Runs to Relevant Changes by [@danny-avila](https://github.com/danny-avila) in [#14388](https://github.com/danny-avila/LibreChat/pull/14388) +- ๐Ÿƒ chore: Bump Mongoose to 8.24.1 to Patch Prototype Pollution by [@danny-avila](https://github.com/danny-avila) in [#14461](https://github.com/danny-avila/LibreChat/pull/14461) +- ๐Ÿ—บ๏ธ chore: Bump PostCSS to 8.5.18 to Patch Source Map Traversal by [@danny-avila](https://github.com/danny-avila) in [#14463](https://github.com/danny-avila/LibreChat/pull/14463) +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.3.4 by [@danny-avila](https://github.com/danny-avila) in [#14482](https://github.com/danny-avila/LibreChat/pull/14482) +- ๐Ÿ‚ chore: Prune Deprecated Packages From the Dependency Tree by [@danny-avila](https://github.com/danny-avila) in [#14483](https://github.com/danny-avila/LibreChat/pull/14483) +- ๐ŸŒฏ chore: Retire Rollup-Era devDependencies After tsdown Migration by [@danny-avila](https://github.com/danny-avila) in [#14496](https://github.com/danny-avila/LibreChat/pull/14496) +- ๐Ÿ“ฆ chore: Bump @librechat/agents to v3.3.5 by [@danny-avila](https://github.com/danny-avila) in [#14506](https://github.com/danny-avila/LibreChat/pull/14506) +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.3.8 by [@danny-avila](https://github.com/danny-avila) in [#14525](https://github.com/danny-avila/LibreChat/pull/14525) +- ๐Ÿงช chore: Add the Activity-Label Prose Eval Harness by [@danny-avila](https://github.com/danny-avila) in [#14527](https://github.com/danny-avila/LibreChat/pull/14527) +- ๐ŸŸฆ chore: Convert Activity-Label Eval Harness to TypeScript by [@danny-avila](https://github.com/danny-avila) in [#14530](https://github.com/danny-avila/LibreChat/pull/14530) +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.3.9 by [@danny-avila](https://github.com/danny-avila) in [#14548](https://github.com/danny-avila/LibreChat/pull/14548) +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.3.11 by [@danny-avila](https://github.com/danny-avila) in [#14562](https://github.com/danny-avila/LibreChat/pull/14562) +- ๐Ÿ“ฆ chore: update `sanitize-html` to latest by [@danny-avila](https://github.com/danny-avila) in [#14573](https://github.com/danny-avila/LibreChat/pull/14573) +- ๐ŸŒ€ ci: Deterministic Circular Dependency Checks by [@danny-avila](https://github.com/danny-avila) in [#14579](https://github.com/danny-avila/LibreChat/pull/14579) +- ๐Ÿ”’ chore: Upgrade react-router-dom to v7.18.2 (security) by [@danny-avila](https://github.com/danny-avila) in [#14582](https://github.com/danny-avila/LibreChat/pull/14582) +- ๐Ÿงช ci: Settle to render-idle before ConversationsSection memo baselines by [@danny-avila](https://github.com/danny-avila) in [#14590](https://github.com/danny-avila/LibreChat/pull/14590) +- ๐Ÿงน chore: Migrate Legacy Duplicate Code Files Blocking Dedupe Index by [@danny-avila](https://github.com/danny-avila) in [#14593](https://github.com/danny-avila/LibreChat/pull/14593) +- ๐Ÿ“ฆ chore: npm audit by [@danny-avila](https://github.com/danny-avila) in [#14640](https://github.com/danny-avila/LibreChat/pull/14640) +- ๐Ÿ›ฐ๏ธ chore: bump `@librechat/agents` to v3.4.0, cover streamed subagent results e2e by [@danny-avila](https://github.com/danny-avila) in [#14647](https://github.com/danny-avila/LibreChat/pull/14647) +- ๐Ÿซ† chore: Remove Published Credential Defaults by [@danny-avila](https://github.com/danny-avila) in [#14680](https://github.com/danny-avila/LibreChat/pull/14680) +- ๐Ÿ‹ chore: add opt-in alternative local stack experiments by [@danny-avila](https://github.com/danny-avila) in [#14678](https://github.com/danny-avila/LibreChat/pull/14678) +- โš™๏ธ ci: Bump GitHub Actions to Node.js 24 Runtimes by [@berry-13](https://github.com/berry-13) in [#14689](https://github.com/danny-avila/LibreChat/pull/14689) +- ๐Ÿ“ฆ chore: bump `@librechat/agents` to v3.4.2 and `npm audit` by [@danny-avila](https://github.com/danny-avila) in [#14702](https://github.com/danny-avila/LibreChat/pull/14702) +- ๐Ÿšฆ ci: Reduce GitHub Actions Runner Pressure by [@berry-13](https://github.com/berry-13) in [#14716](https://github.com/danny-avila/LibreChat/pull/14716) +- ๐Ÿงฉ ci: Close Workflow Path-Filter Gaps by [@danny-avila](https://github.com/danny-avila) in [#14728](https://github.com/danny-avila/LibreChat/pull/14728) +- ๐Ÿ›ป ci: Move the ESLint Config Sweep Into Its Own Job by [@danny-avila](https://github.com/danny-avila) in [#14742](https://github.com/danny-avila/LibreChat/pull/14742) +- ๐Ÿงท ci: Enforce Durable Agent Finalization for E2E tests by [@danny-avila](https://github.com/danny-avila) in [#14740](https://github.com/danny-avila/LibreChat/pull/14740) +- ๐Ÿชถ chore: Aggregate Empty MCP Tool Logs by [@danny-avila](https://github.com/danny-avila) in [#14767](https://github.com/danny-avila/LibreChat/pull/14767) +- ๐Ÿ“ฆ chore: Update `@librechat/agents` to v3.4.6 by [@danny-avila](https://github.com/danny-avila) in [#14781](https://github.com/danny-avila/LibreChat/pull/14781) +- ๐ŸŒ ci: Harden Locize Translation Sync by [@danny-avila](https://github.com/danny-avila) in [#14784](https://github.com/danny-avila/LibreChat/pull/14784) +- ๐Ÿ”Œ chore: Bump the MCP SDK to 1.30.0 and Parse Content-Type Instead of Searching It by [@danny-avila](https://github.com/danny-avila) in [#14820](https://github.com/danny-avila/LibreChat/pull/14820) +- ci: gate the e2e activity-phase DOM assertions on the persisted phase by [@danny-avila](https://github.com/danny-avila) in [#14821](https://github.com/danny-avila/LibreChat/pull/14821) + +### ๐ŸŒ Internationalization + +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14053](https://github.com/danny-avila/LibreChat/pull/14053) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14070](https://github.com/danny-avila/LibreChat/pull/14070) +- ๐ŸŒ i18n: Localize Token Balance Error Message by [@Philipp-Voss](https://github.com/Philipp-Voss) in [#14169](https://github.com/danny-avila/LibreChat/pull/14169) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14266](https://github.com/danny-avila/LibreChat/pull/14266) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14307](https://github.com/danny-avila/LibreChat/pull/14307) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14376](https://github.com/danny-avila/LibreChat/pull/14376) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14406](https://github.com/danny-avila/LibreChat/pull/14406) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14460](https://github.com/danny-avila/LibreChat/pull/14460) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14598](https://github.com/danny-avila/LibreChat/pull/14598) +- ๐ŸŒ i18n: Update translation.json with latest translations by [@danny-avila](https://github.com/danny-avila) in [#14739](https://github.com/danny-avila/LibreChat/pull/14739) +- ๐ŸŒ chore: Restore English Localization Source Values by [@danny-avila](https://github.com/danny-avila) in [#14743](https://github.com/danny-avila/LibreChat/pull/14743) + +## New Contributors + +- [@alexkorep](https://github.com/alexkorep) made their first contribution in [#14034](https://github.com/danny-avila/LibreChat/pull/14034) +- [@jakacenta](https://github.com/jakacenta) made their first contribution in [#14046](https://github.com/danny-avila/LibreChat/pull/14046) +- [@Zirkonium88](https://github.com/Zirkonium88) made their first contribution in [#13989](https://github.com/danny-avila/LibreChat/pull/13989) +- [@arjunvijay24](https://github.com/arjunvijay24) made their first contribution in [#14040](https://github.com/danny-avila/LibreChat/pull/14040) +- [@mahirhir](https://github.com/mahirhir) made their first contribution in [#13996](https://github.com/danny-avila/LibreChat/pull/13996) +- [@Osamaali313](https://github.com/Osamaali313) made their first contribution in [#13999](https://github.com/danny-avila/LibreChat/pull/13999) +- [@Philipp-Voss](https://github.com/Philipp-Voss) made their first contribution in [#14169](https://github.com/danny-avila/LibreChat/pull/14169) +- [@VictorEPlus](https://github.com/VictorEPlus) made their first contribution in [#14172](https://github.com/danny-avila/LibreChat/pull/14172) +- [@adamscross04](https://github.com/adamscross04) made their first contribution in [#14177](https://github.com/danny-avila/LibreChat/pull/14177) +- [@manisrinivasan2k1](https://github.com/manisrinivasan2k1) made their first contribution in [#14082](https://github.com/danny-avila/LibreChat/pull/14082) +- [@jomspk](https://github.com/jomspk) made their first contribution in [#14232](https://github.com/danny-avila/LibreChat/pull/14232) +- [@jjhidalgar-celonis](https://github.com/jjhidalgar-celonis) made their first contribution in [#14254](https://github.com/danny-avila/LibreChat/pull/14254) +- [@Aho-Bakaa](https://github.com/Aho-Bakaa) made their first contribution in [#14262](https://github.com/danny-avila/LibreChat/pull/14262) +- [@joshbla](https://github.com/joshbla) made their first contribution in [#13930](https://github.com/danny-avila/LibreChat/pull/13930) +- [@unsnow-iac](https://github.com/unsnow-iac) made their first contribution in [#14436](https://github.com/danny-avila/LibreChat/pull/14436) +- [@schumajs](https://github.com/schumajs) made their first contribution in [#14538](https://github.com/danny-avila/LibreChat/pull/14538) +- [@cyphercodes](https://github.com/cyphercodes) made their first contribution in [#14507](https://github.com/danny-avila/LibreChat/pull/14507) +- [@likeabas](https://github.com/likeabas) made their first contribution in [#14764](https://github.com/danny-avila/LibreChat/pull/14764) +- [@jtodaroii](https://github.com/jtodaroii) made their first contribution in [#14774](https://github.com/danny-avila/LibreChat/pull/14774) +- [@lizzykerrigan](https://github.com/lizzykerrigan) made their first contribution in [#14791](https://github.com/danny-avila/LibreChat/pull/14791) +- [@mihidumh](https://github.com/mihidumh) made their first contribution in [#14810](https://github.com/danny-avila/LibreChat/pull/14810) +- [@snapydziuba](https://github.com/snapydziuba) made their first contribution in [#14761](https://github.com/danny-avila/LibreChat/pull/14761) + +**Full Changelog**: [v0.8.7...v0.8.8-rc1](https://github.com/danny-avila/LibreChat/compare/v0.8.7...v0.8.8-rc1) diff --git a/content/docs/configuration/authentication/OAuth2-OIDC/google.mdx b/content/docs/configuration/authentication/OAuth2-OIDC/google.mdx index e1da90c42..75308e2a1 100644 --- a/content/docs/configuration/authentication/OAuth2-OIDC/google.mdx +++ b/content/docs/configuration/authentication/OAuth2-OIDC/google.mdx @@ -70,6 +70,7 @@ description: Learn how to configure LibreChat to use Google for user authenticat - Add a valid `Authorized redirect URIs` - Example for localhost: `http://localhost:3080/oauth/google/callback` - Example for a domain: `https://example.com/oauth/google/callback` + - If using the Admin Panel: `https://example.com/api/admin/oauth/google/callback` ![image](https://github.com/danny-avila/LibreChat/assets/138638445/0db34b19-d780-4651-9c2f-d33e24a74d55) @@ -93,3 +94,7 @@ GOOGLE_CALLBACK_URL=/oauth/google/callback - Save the `.env` file > Note: If using docker, run `docker compose up -d` to apply the .env configuration changes + +## Admin Panel Sessions + +The [Admin Panel](/docs/features/admin_panel) uses the same `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, but its callback is `${DOMAIN_SERVER}/api/admin/oauth/google/callback`. Its Google flow requests offline access and consent so an expired LibreChat admin token can be refreshed. LibreChat rechecks the user's identity, ban state, allowed domain, tenant, and current admin access on every refresh. diff --git a/content/docs/configuration/authentication/OAuth2-OIDC/index.mdx b/content/docs/configuration/authentication/OAuth2-OIDC/index.mdx index 95d9d168e..230ab714b 100644 --- a/content/docs/configuration/authentication/OAuth2-OIDC/index.mdx +++ b/content/docs/configuration/authentication/OAuth2-OIDC/index.mdx @@ -28,6 +28,17 @@ This section will cover how to configure OAuth2 and OpenID Connect with LibreCha - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak) - [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse) +### OpenID JWT User Cache + +High-request-rate deployments can set `AUTH_USER_CACHE_MODE=on` to cache the user document resolved for OpenID JWT authentication for five seconds. This reduces repeated database reads during short request bursts without extending the authentication token lifetime. + +The cache is off by default and requires `USE_REDIS=true` with the `AUTH_USER_DOC` namespace backed by Redis. LibreChat disables the mode and logs a warning when those requirements are not met. Cached documents are sanitized before storage and invalidated when the user is updated. + +```bash filename=".env" +USE_REDIS=true +AUTH_USER_CACHE_MODE=on +``` + ## Troubleshooting OpenID Connect If you encounter issues with OpenID Connect authentication: diff --git a/content/docs/configuration/authentication/index.mdx b/content/docs/configuration/authentication/index.mdx index 29c07407c..37ef2539c 100644 --- a/content/docs/configuration/authentication/index.mdx +++ b/content/docs/configuration/authentication/index.mdx @@ -12,28 +12,54 @@ Here's an overview of the general configuration. > **Note:** OpenID and SAML do not support the ability to disable only registration. +Setting `ALLOW_EMAIL_LOGIN=false` hides the email login form and rejects local or LDAP credential requests to `/api/auth/login`; OAuth, OpenID Connect, and SAML sign-in are unaffected. `ALLOW_EMAIL_LOGIN_OVERRIDE=true` is intended only for a controlled API integration that still needs credential login while the form is hidden. Every override use logs the request IP, so protect and monitor that route carefully. + Quick Tips: - Even with registration disabled, you can add users directly to the database using [the create-user script](#create-user-script) detailed below. - To delete a user, you can use [the delete-user script](#delete-user-script) also detailed below. - - ## Session Expiry and Refresh Token - Default values: session expiry: 15 minutes, refresh token expiry: 7 days @@ -72,16 +98,17 @@ sequenceDiagram ## JWT Secret and Refresh Secret -- You should use new secure values. The examples given are 32-byte keys (64 characters in hex). - - Use this tool to generate some quickly: **[JWT Keys](/toolkit/creds_generator)** +Use unique values of at least 32 bytes. Generate permanent values with the [Credentials Generator](/toolkit/creds_generator), store them securely, and provide the same values to every LibreChat replica. + +Values must be non-negative safe integers; invalid values are ignored. When both header and request timeouts are enabled, LibreChat clamps the header timeout to the request timeout if it is higher. Node checks header and request expiry on a 30-second connection sweep, so values below `30000` are not enforced at exact millisecond precision. Bun currently accepts these settings but does not enforce them; LibreChat logs a warning when the API server runs under Bun. + ### Trust proxy Use the address that is at most n number of hops away from the Express application. @@ -56,28 +91,37 @@ Refer to [Express.js - trust proxy](https://expressjs.com/en/guide/behind-proxie ### Credentials Configuration -To securely store credentials, you need a fixed key and IV. You can set them here for prod and dev environments. +LibreChat uses `CREDS_KEY` and `CREDS_IV` to encrypt supported credentials stored in the database. Configure fixed, unique values for production and share the same values across every replica. - - **Warning:** If you don't set `CREDS_KEY` and `CREDS_IV`, the app will crash on startup. - You can - use this [Key Generator](/toolkit/creds_generator) to generate them quickly. +When any of `CREDS_KEY`, `CREDS_IV`, `JWT_SECRET`, or `JWT_REFRESH_SECRET` is blank, LibreChat first reuses a valid value from the temporary credentials file. If none exists, it generates a cryptographically random value and writes the file with owner-only permissions. Explicit environment values always take precedence. LibreChat refuses to use `.env` or `.env.example` as the generated file path, preventing accidental replacement of either configuration file. + +The bundled Docker Compose files persist `/app/data/.env.temp` in the `librechat-data` volume, so a single Compose deployment can restart without changing these generated values. If the file cannot be persisted, the values are process-local and sessions or encrypted records may become inaccessible after restart. + + + Temporary generation is a bootstrap convenience, not a credential-rotation system. Before production use, generate permanent values with the [Credentials Generator](/toolkit/creds_generator), store them in your secret manager, and provide the same values to every replica. Changing an established key does not re-encrypt existing records. LibreChat records credential fingerprints in the database and warns when active values drift; do not overwrite that marker instead of performing a controlled migration. ### Static File Handling @@ -231,14 +275,11 @@ If you are using an online database, the URI format is `mongodb+srv:// ]} /> -Alternatively you can use `documentDb` that emulates `mongoDb` but it: - -- does not support `retryWrites` - use `retryWrites=false` -- requires TLS connection, hence use parameters `tls=true` to enable TLS and `tlsCAFile=/path-to-ca/bundle.pem` to point to the AWS provided CA bundle file +Amazon DocumentDB 5.0+ instance-based clusters are a supported target. DocumentDB requires `retryWrites=false` and TLS with the AWS CA bundle; elastic clusters are unsupported because they do not provide unique indexes. A typical URI has this form: -The URI for `documentDb` will look like: +`mongodb://username:password@cluster:27017/librechat?tls=true&tlsCAFile=/path-to-ca/global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false` -- `mongodb+srv://username:password@domain/dbname?retryWrites=false&tls=true&tlsCAFile=/path-to-ca/bundle.pem` +DocumentDB 4.0 can run with reduced partial-unique-index enforcement. See [Amazon DocumentDB Compatibility](/docs/user_guides/mongodb#amazon-documentdb-compatibility) for the supported target and caveats. See also: @@ -268,7 +309,7 @@ To configure LibreChat for local use or custom domain deployment, set the follow [ 'ADMIN_PANEL_URL', 'string', - 'External admin panel base URL used for admin OAuth/SSO redirects when the admin panel is hosted separately. Do not include a trailing slash.', + 'External admin panel base URL used for admin OAuth/SSO redirects and the admin-only Settings > General link. Do not include a trailing slash.', 'ADMIN_PANEL_URL=https://admin.example.com/admin', ], [ @@ -387,6 +428,50 @@ Note: `DEBUG_CONSOLE` is not recommended, as the outputs can be quite verbose, a ]} /> +### Langfuse Tracing and Tenant Fanout + +Use the standard Langfuse variables for one central observability project. The optional fanout deployment can additionally route tenant traces, media, and feedback scores to tenant-specific Langfuse projects. See [Langfuse Tracing](/docs/configuration/langfuse) for setup, in-app connection management, and architecture. + +'], + ['LANGFUSE_FANOUT_CENTRAL_MEDIA_EXPORT_DISABLED', 'boolean', 'Disable central media fanout without disabling central traces.', '# LANGFUSE_FANOUT_CENTRAL_MEDIA_EXPORT_DISABLED=false'], + ['LANGFUSE_FANOUT_TENANT_DESTINATIONS', 'string', 'Comma-separated destination key and base URL mappings allowed at startup.', '# LANGFUSE_FANOUT_TENANT_DESTINATIONS=eu=https://cloud.langfuse.com,us=https://us.cloud.langfuse.com'], + ['LANGFUSE_FANOUT_TRACE_DESTINATION_KEYS', 'string', 'Destination keys supported by the collector routing configuration.', '# LANGFUSE_FANOUT_TRACE_DESTINATION_KEYS=eu,us,jp'], + ['LANGFUSE_FANOUT_PUBLIC_URL', 'string', 'Gateway base URL used to create one-time media upload URLs.', '# LANGFUSE_FANOUT_PUBLIC_URL=http://langfuse-fanout-collector:4318'], + ['LANGFUSE_FANOUT_TRACE_COLLECTOR_URL', 'string', 'Internal gateway-to-collector trace endpoint.', '# LANGFUSE_FANOUT_TRACE_COLLECTOR_URL=http://langfuse-fanout-otel:4319'], + ['LANGFUSE_FANOUT_REDIS_URI', 'string', 'Redis URI for one-time media upload plans.', '# LANGFUSE_FANOUT_REDIS_URI=redis://langfuse-fanout-redis:6379'], + ['LANGFUSE_FANOUT_REDIS_USERNAME', 'string', 'Optional Redis username for the fanout gateway.', '# LANGFUSE_FANOUT_REDIS_USERNAME='], + ['LANGFUSE_FANOUT_REDIS_PASSWORD', 'string', 'Optional Redis password for the fanout gateway.', '# LANGFUSE_FANOUT_REDIS_PASSWORD='], + ['LANGFUSE_FANOUT_REDIS_KEY_PREFIX', 'string', 'Redis key prefix for fanout media plans.', '# LANGFUSE_FANOUT_REDIS_KEY_PREFIX=langfuse-fanout'], + ['LANGFUSE_FANOUT_OTEL_RECEIVER_ENDPOINT', 'string', 'Internal collector receiver bind address.', '# LANGFUSE_FANOUT_OTEL_RECEIVER_ENDPOINT=0.0.0.0:4319'], + ['LANGFUSE_FANOUT_TENANT_EU_BASE_URL', 'string', 'Static EU destination URL for the included Compose collector.', '# LANGFUSE_FANOUT_TENANT_EU_BASE_URL=https://cloud.langfuse.com'], + ['LANGFUSE_FANOUT_TENANT_US_BASE_URL', 'string', 'Static US destination URL for the included Compose collector.', '# LANGFUSE_FANOUT_TENANT_US_BASE_URL=https://us.cloud.langfuse.com'], + ['LANGFUSE_FANOUT_TENANT_JP_BASE_URL', 'string', 'Static JP destination URL for the included Compose collector.', '# LANGFUSE_FANOUT_TENANT_JP_BASE_URL=https://jp.cloud.langfuse.com'], + ['LANGFUSE_FANOUT_UPSTREAM_TIMEOUT', 'duration', 'Timeout for gateway requests to Langfuse and media upload URLs.', '# LANGFUSE_FANOUT_UPSTREAM_TIMEOUT=30s'], + ['LANGFUSE_FANOUT_METRICS_SECRET', 'string', 'Bearer token required to scrape the gateway metrics endpoint.', '# LANGFUSE_FANOUT_METRICS_SECRET='], + ['LANGFUSE_FANOUT_MEMORY_LIMIT_MIB', 'number', 'Collector memory limit in MiB.', '# LANGFUSE_FANOUT_MEMORY_LIMIT_MIB=256'], + ['LANGFUSE_FANOUT_MEMORY_SPIKE_LIMIT_MIB', 'number', 'Collector memory spike allowance in MiB.', '# LANGFUSE_FANOUT_MEMORY_SPIKE_LIMIT_MIB=64'], + ['LANGFUSE_FANOUT_BATCH_TIMEOUT', 'duration', 'Collector batch flush timeout.', '# LANGFUSE_FANOUT_BATCH_TIMEOUT=1s'], + ['LANGFUSE_FANOUT_BATCH_SEND_SIZE', 'number', 'Collector batch send size.', '# LANGFUSE_FANOUT_BATCH_SEND_SIZE=128'], + ['LANGFUSE_FANOUT_METADATA_CARDINALITY_LIMIT', 'number', 'Collector metadata cardinality limit.', '# LANGFUSE_FANOUT_METADATA_CARDINALITY_LIMIT=1000'], + ]} +/> + +In a single-tenant deployment without complete `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` environment credentials, an authorized administrator can configure one encrypted connection under **Settings โ†’ Langfuse**. Complete environment credentials take precedence and hide that setting. Fanout deployments use the same setting for the tenant connection when fanout and tenant export are enabled. + ### OpenTelemetry Tracing LibreChat can emit backend OpenTelemetry traces for general API, HTTP, MongoDB, Mongoose, Redis, and outbound request visibility. Redis command-level spans are opt-in so default traces stay high-level. Use Langfuse for GenAI-specific prompt/model observability. @@ -547,6 +632,8 @@ LibreChat can publish browser Real User Monitoring (RUM) telemetry to HyperDX-co In `publicToken` mode, the browser sends telemetry directly to `RUM_URL` with `RUM_PUBLIC_TOKEN`. In `proxy` mode, the browser sends telemetry through LibreChat; the backend validates the user session, strips app authentication headers, and forwards telemetry to `RUM_PROXY_TARGET_URL`. Invalid or expired sessions are dropped with a `204` response so browser telemetry failures do not surface normal API authentication errors. Proxy outcomes are counted in `rum_proxy_requests_total` with `endpoint` and `result` labels on the LibreChat API `/metrics` endpoint. +For sampled page loads, LibreChat emits one `page-load-diagnostics` action when First Contentful Paint is observed. It includes navigation timing attribution such as time to first byte, first-byte-to-FCP time, service-worker timing, navigation type, and a normalized route instead of raw conversation IDs. RUM also records early page lifecycle, service-worker, stale-asset recovery, and single-page-app route-change events. Diagnostics are best-effort and never delay startup or trigger recovery behavior; early events are discarded when the page is not sampled. + ### Configuration Path - `librechat.yaml` Specify an alternative location for the LibreChat configuration file. @@ -582,6 +669,35 @@ Deployment Skills are loaded read-only at startup from the filesystem and expose Restart LibreChat after changing this directory or any files inside it. Deployment-provided Skills take precedence over persisted Skills with the same name. +### Agent Plugins (Experimental) + +LibreChat can load experimental Agent Plugins from immediate child directories at startup. A plugin can bundle deployment Skills, MCP servers, and optional command hooks. + + + +See [Agent Plugins](/docs/features/agent_plugins) for package layout, schema versions, supported components, precedence, and current limitations. + ### Configuration Validation By default, LibreChat will exit with an error (exit code 1) if the `librechat.yaml` configuration file contains validation errors. This fail-fast behavior helps catch configuration issues early in deployment pipelines and prevents running with unintended default settings. @@ -779,7 +895,7 @@ see: [Anthropic Endpoint](/docs/configuration/pre_configured_ai/anthropic) 'ANTHROPIC_MODELS', 'string', 'Comma-separated list of Anthropic models to use.', - '# ANTHROPIC_MODELS=claude-fable-5,claude-opus-4-8,claude-opus-4-7,claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-20250514,claude-3-7-sonnet-20250219,claude-3-5-sonnet-20241022,claude-3-5-haiku-20241022', + '# ANTHROPIC_MODELS=claude-fable-5,claude-opus-5,claude-opus-4-8,claude-opus-4-7,claude-sonnet-5,claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-20250514,claude-3-7-sonnet-20250219,claude-3-5-sonnet-20241022,claude-3-5-haiku-20241022', ], [ 'ANTHROPIC_REVERSE_PROXY', @@ -820,8 +936,8 @@ You can also use Anthropic Claude models through Google Cloud Vertex AI. For det [ 'ANTHROPIC_VERTEX_REGION', 'string', - 'The Google Cloud region for Vertex AI. Default: us-east5.', - 'ANTHROPIC_VERTEX_REGION=us-east5', + 'The Google Cloud location for Vertex AI. Default: us-east5. Use global, us, or eu for Opus 4.7+, Opus 5, Sonnet 5, and Fable/Mythos 5.', + 'ANTHROPIC_VERTEX_REGION=global', ], ]} /> @@ -874,7 +990,7 @@ See: [AWS Bedrock Setup](/docs/configuration/pre_configured_ai/bedrock) 'BEDROCK_AWS_MODELS', 'string', 'Comma-separated list of Bedrock model IDs. If omitted, all known supported models are included.', - '# BEDROCK_AWS_MODELS=anthropic.claude-fable-5,anthropic.claude-opus-4-8,anthropic.claude-opus-4-7,anthropic.claude-sonnet-4-6,meta.llama3-1-8b-instruct-v1:0', + '# BEDROCK_AWS_MODELS=global.anthropic.claude-fable-5,global.anthropic.claude-opus-5,global.anthropic.claude-opus-4-8,global.anthropic.claude-opus-4-7,global.anthropic.claude-sonnet-5,global.anthropic.claude-sonnet-4-6,meta.llama3-1-8b-instruct-v1:0', ], ]} /> @@ -937,13 +1053,13 @@ Follow these instructions to setup the [Google Endpoint](/docs/configuration/pre 'GOOGLE_MODELS', 'string', 'Available Gemini API Google models, separated by commas.', - 'GOOGLE_MODELS=gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash,gemini-2.0-flash-lite', + 'GOOGLE_MODELS=gemini-3.7-flash,gemini-3.6-flash,gemini-3.5-flash,gemini-3.5-flash-lite,gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash,gemini-2.0-flash-lite', ], [ 'GOOGLE_MODELS', 'string', 'Available Vertex AI Google models, separated by commas.', - 'GOOGLE_MODELS=gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash-001,gemini-2.0-flash-lite-001', + 'GOOGLE_MODELS=gemini-3.7-flash,gemini-3.6-flash,gemini-3.5-flash,gemini-3.5-flash-lite,gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash-001,gemini-2.0-flash-lite-001', ], [ 'GOOGLE_TITLE_MODEL', @@ -1182,6 +1298,35 @@ See detailed instructions here: **[OpenWeather](/docs/configuration/tools/openwe ]} /> +## File Uploads + + + +With `FILE_UPLOAD_SSE_ENABLED=true`, clients that request `text/event-stream` receive one-second heartbeat events while upload processing is still running, followed by a `data` or `error` event and a final `close` event. Clients that do not request SSE continue to receive the normal JSON response. This is useful when a reverse proxy would otherwise close an idle connection during long OCR, parsing, or RAG work. + +The remote fetch controls apply when LibreChat ingests an HTTP or HTTPS file URL into local, Firebase, Azure, or S3/CloudFront storage. LibreChat checks both a declared `Content-Length` and the bytes actually streamed, so the limit still applies when the remote server omits or misstates its length. These controls are independent of the per-upload limits in [`fileConfig`](/docs/configuration/librechat_yaml/object_structure/file_config). + ## Code Interpreter The Code Interpreter API provides a secure environment for executing code and managing files. See: [Code Interpreter API](/docs/features/code_interpreter) @@ -1197,9 +1342,27 @@ The Code Interpreter API provides a secure environment for executing code and ma [ 'LIBRECHAT_CODE_BASEURL', 'string', - 'Custom base URL for the Code Interpreter API (Enterprise plans only).', + 'Base URL for your Code Interpreter service.', '# LIBRECHAT_CODE_BASEURL=https://your-custom-domain.com', ], + [ + 'CODE_SANDBOX_PREWARM', + 'boolean', + 'Prewarm stateful per-conversation sandboxes in parallel with model generation. Set to false to disable. Default: true.', + '# CODE_SANDBOX_PREWARM=true', + ], + [ + 'CODE_SANDBOX_COLD_AFTER_MS', + 'number', + 'Time in milliseconds before LibreChat treats a tracked sandbox as cold. Default: 2100000 (35 minutes).', + '# CODE_SANDBOX_COLD_AFTER_MS=2100000', + ], + [ + 'LIBRECHAT_CODE_IMAGE_CHUNK_BYTES', + 'number', + 'Bytes read per sandbox image chunk. Lower this when the runner has a smaller stdout limit. Default: 32768.', + '# LIBRECHAT_CODE_IMAGE_CHUNK_BYTES=32768', + ], ]} /> @@ -1224,10 +1387,10 @@ For more info, including pre-made container images for self-hosting with metric ## Search (Meilisearch) -Enables search in messages and conversations: +Search is disabled by default. Enable it only after configuring Meilisearch with a unique master key: > Note: If you're not using docker, it requires the installation of the free self-hosted Meilisearch or a paid remote plan @@ -1258,7 +1421,7 @@ For the API server to connect to the search server. Replace '0.0.0.0' with 'meil ]} /> -This master key must be at least 16 bytes, composed of valid UTF-8 characters. MeiliSearch will throw an error and refuse to launch if no master key is provided or if it is under 16 bytes. MeiliSearch will suggest a secure autogenerated master key. This is a ready-made secure key for docker-compose, you can replace it with your own. +This master key must be at least 16 bytes of valid UTF-8. Generate a unique value and give the same key to LibreChat and the Meilisearch service. Search requires both `SEARCH=true` and a configured `MEILI_MASTER_KEY`. + ### Moderation The Automated Moderation System uses a scoring mechanism to track user violations. As users commit actions like excessive logins, registrations, or messaging, they accumulate violation scores. Upon reaching a set threshold, the user and their IP are temporarily banned. This system ensures platform security by monitoring and penalizing rapid or suspicious activities. @@ -1476,6 +1652,63 @@ Prevents brute force attacks and spam registrations by limiting login attempts a ]} /> +#### Password reset and email verification rate limiting + +LibreChat applies separate IP-based limits to requesting an email and submitting the token from that email. This prevents repeated token guesses without forcing deployments to use the same limit for email delivery and token validation. + + + #### Score for each violation +##### Queued Attachment TTL Limiter: + +The `/files/usage` endpoint renews a bounded TTL hold for attachments waiting in queued Agent messages. It has a separate per-user limiter so metadata renewals do not consume the upload quota. + + + #### Import conversation rate limiting Limits how often users can import conversations to prevent abuse. @@ -1946,6 +2212,12 @@ see: **[Authentication System](/docs/configuration/authentication)** 'Enable or disable ONLY email login.', 'ALLOW_EMAIL_LOGIN=true', ], + [ + 'ALLOW_EMAIL_LOGIN_OVERRIDE', + 'boolean', + 'Permit direct API email login while ALLOW_EMAIL_LOGIN=false. Each use is logged. Default: false.', + '# ALLOW_EMAIL_LOGIN_OVERRIDE=false', + ], [ 'ALLOW_REGISTRATION', 'boolean', @@ -2023,8 +2295,7 @@ see: **[Authentication System](/docs/configuration/authentication)** - JWT Settings: -You should use new secure values. The examples given are 32-byte keys (64 characters in hex). -Use this replit to generate some quickly: **[JWT Keys](/toolkit/creds_generator)** +Use unique values of at least 32 bytes. Generate permanent values for production with the [Credentials Generator](/toolkit/creds_generator). @@ -37,6 +72,8 @@ Add the following Langfuse-related environment variables to your `.env` file in # Langfuse Configuration LANGFUSE_PUBLIC_KEY=pk-lf-*** LANGFUSE_SECRET_KEY=sk-lf-*** +# LANGFUSE_PROJECT_ID=project-id +# LANGFUSE_SAMPLE_RATE=1 # ๐Ÿ‡ช๐Ÿ‡บ EU Data Region LANGFUSE_BASE_URL=https://cloud.langfuse.com @@ -50,6 +87,129 @@ LANGFUSE_BASE_URL=https://cloud.langfuse.com `http://localhost:3000` for local development). +When both environment keys are present, LibreChat uses them for the central project and hides **Settings โ†’ Langfuse**. `LANGFUSE_TRACING_ENABLED=false` or `LANGFUSE_SAMPLE_RATE=0` disables both traces and feedback scores. Fractional sampling makes one deterministic decision per trace; sampled-out traces do not receive later feedback scores. + +## Tenant Fanout (Optional) + +Langfuse fanout lets a multi-tenant LibreChat deployment export each eligible trace and its media to both a central Langfuse project and a tenant-specific project. The feature is opt-in and adds a gateway plus an internal OpenTelemetry collector; normal single-project tracing above is unchanged when fanout is not deployed. + +Fanout uses two configuration layers: + +- Deployment environment variables define the central project, gateway, and allowed tenant destinations at startup. +- **Settings โ†’ Langfuse** supplies the tenant's enabled state, public key, encrypted secret key, verified project ID, and one allowed destination. Keys can be changed at runtime without restarting the gateway. + +The included Compose override supports the `eu`, `us`, and `jp` Langfuse Cloud destinations: + +```sh filename=".env" +LANGFUSE_BASE_URL=https://cloud.langfuse.com +LANGFUSE_FANOUT_CENTRAL_BASE_URL=https://cloud.langfuse.com +LANGFUSE_FANOUT_CENTRAL_AUTH_HEADER="Basic " +LANGFUSE_FANOUT_CENTRAL_MEDIA_UPLOAD_DISABLED=false +LANGFUSE_FANOUT_TENANT_DESTINATIONS="eu=https://cloud.langfuse.com,us=https://us.cloud.langfuse.com,jp=https://jp.cloud.langfuse.com" +LANGFUSE_FANOUT_TRACE_DESTINATION_KEYS=eu,us,jp +LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED=false +``` + +Start the regular Compose stack with the fanout override: + +```sh +docker compose -f docker-compose.yml -f docker-compose.langfuse-fanout.yml up -d +``` + +The override enables `LANGFUSE_FANOUT_ENABLED`, points LibreChat at the gateway, and starts the collector and private Redis services. For the deployed stack, combine `deploy-compose.yml` with `deploy-compose.langfuse-fanout.yml` instead. + +The gateway listens on `:4318` by default. Custom deployments can override its bind address with `LANGFUSE_FANOUT_LISTEN_ADDR`; the included Compose and Helm configurations already route the standard gateway port. + +### Helm Deployment + +The Compose overrides build the gateway locally, but Kubernetes needs an image available from a registry. From the LibreChat repository root, build and push the gateway before installing the chart: + +```sh +docker build \ + -f otel/langfuse-fanout/Dockerfile \ + -t registry.example.com/librechat-langfuse-fanout: . +docker push registry.example.com/librechat-langfuse-fanout: +``` + +Create a Kubernetes Secret containing the full central Langfuse Basic auth header. Its value is `Basic ` followed by base64-encoded `:` credentials: + +```sh +kubectl create secret generic langfuse-central \ + --from-literal=LANGFUSE_FANOUT_CENTRAL_AUTH_HEADER='Basic ' +``` + +Enable the fanout deployment in Helm values. This example uses the bundled Redis chart; set `langfuseFanout.redis.uri` instead when using an external Redis service. + +```yaml filename="values.yaml" +redis: + enabled: true + +langfuseFanout: + enabled: true + image: + repository: registry.example.com/librechat-langfuse-fanout + tag: '' + pullPolicy: IfNotPresent + central: + baseUrl: https://cloud.langfuse.com + authHeaderSecret: + name: langfuse-central + key: LANGFUSE_FANOUT_CENTRAL_AUTH_HEADER + metrics: + secret: + name: librechat-metrics + key: METRICS_SECRET + tenant: + destinations: + eu: + baseUrl: https://cloud.langfuse.com + us: + baseUrl: https://us.cloud.langfuse.com + jp: + baseUrl: https://jp.cloud.langfuse.com + upstreamTimeout: 30s + publicUrl: '' + otelCollector: + receiverEndpoint: 127.0.0.1:4319 + redis: + uri: '' + username: '' + passwordSecret: + name: '' + key: REDIS_PASSWORD + keyPrefix: langfuse-fanout + memoryLimitMiB: 256 + memorySpikeLimitMiB: 64 + batchTimeout: 1s + batchSendSize: 128 + metadataCardinalityLimit: 1000 +``` + +The metrics Secret is optional, but `/metrics` returns `401` unless `langfuseFanout.metrics.secret` supplies a bearer token. Create it separately when metrics scraping is required: + +```sh +kubectl create secret generic librechat-metrics \ + --from-literal=METRICS_SECRET='' +``` + +The chart renders one Deployment with a gateway container on port `4318` and an internal OpenTelemetry Collector sidecar on port `4319`; only the gateway is exposed by the Service. It also injects `LANGFUSE_FANOUT_ENABLED` and the internal `LANGFUSE_FANOUT_COLLECTOR_URL` into LibreChat unless those keys are already set in `librechat.configEnv`. + +Redis stores short-lived, one-time media upload plans so create and upload requests can reach different gateway replicas. For an external authenticated Redis service, set `langfuseFanout.redis.uri`, optional `username`, and `passwordSecret`; keep credentials out of the URI because the URI is rendered directly into the Deployment environment. With the bundled Redis chart and authentication enabled, provide a compatible password Secret or an explicitly authenticated external URI. + +Scale fanout manually with `langfuseFanout.replicaCount`; the chart does not create a fanout HPA. Liveness and readiness probes use `/healthz` and can be customized under `langfuseFanout.livenessProbe` and `langfuseFanout.readinessProbe`. + +Additional deployment overrides include `langfuseFanout.service` for the Service type, port, and annotations; `resources`, `podAnnotations`, and `podLabels` for the gateway Pod; and `otelCollector.image` and `otelCollector.resources` for the sidecar. If you change `langfuseFanout.traceCollectorUrl` or `otelCollector.receiverEndpoint`, keep both values pointed at the same internal collector listener. + +The stored top-level `langfuse` object contains `enabled`, `publicKey`, encrypted `secretKey`, verified `projectId`, server-generated `secretKeyPreview`, and `destination`. Treat it as API-managed configuration: do not submit preview fields or encrypted payloads back as secrets. The earlier `displaySecretKey` and nested `fanout.enabled` fields are no longer used. + +Tenant export occurs only when fanout and the collector URL are enabled, the saved connection is enabled with valid keys, and `destination` matches an allowed startup destination. Other traces can still flow to the central project. Set `LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED=true` as an emergency switch to stop tenant trace and feedback-score export while retaining central export; this also hides the in-app connection setting until tenant export is restored. + +Set `LANGFUSE_FANOUT_CENTRAL_MEDIA_UPLOAD_DISABLED=true` to prevent the LibreChat SDK from creating media uploads for central or fallback collector traces; tenant-routed media uploads are unchanged. This app-side switch is distinct from the gateway-side `LANGFUSE_FANOUT_CENTRAL_MEDIA_EXPORT_DISABLED`, which blocks central media forwarding after an upload reaches the gateway. + +Trace and media traffic goes through the fanout gateway. Feedback scores are sent directly from LibreChat: central scores use `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and `LANGFUSE_BASE_URL`, while tenant scores use tenant app configuration. + +See the [Langfuse fanout deployment reference](https://github.com/danny-avila/LibreChat/blob/dev/otel/langfuse-fanout/README.md) for every gateway variable, custom destination setup, metrics, scaling, and Redis behavior. + ## Restart LibreChat After adding the environment variables, restart your LibreChat instance to apply the changes: @@ -67,6 +227,8 @@ Once LibreChat is restarted with Langfuse configured, you will see a new trace f [Link to trace in the Langfuse UI](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/57b4aa20a258a2e9e2d1ce2e4eacb21c?observation=06f5341a68d723b1×tamp=2026-02-04T13%3A02%3A54.248Z&traceId=57b4aa20a258a2e9e2d1ce2e4eacb21c) +Administrators with `access:admin` and `manage:configs:langfuse` can also open the conversation's **Context Usage** breakdown and select **View session in Langfuse**. The link appears only after generation finishes and when the conversation contains at least one sampled trace sent to the active in-app Langfuse connection. It points to that connection's verified destination and project; it is not shown for environment-managed credentials, disabled connections, sampled-out conversations, or users without Langfuse configuration access. + ## Message Feedback Scores When Langfuse tracing is configured, LibreChat also sends message feedback to Langfuse as a `user-feedback` BOOLEAN score on the matching trace. A thumbs-up rating is sent as `1`, a thumbs-down rating is sent as `0`, and any selected feedback tag or comment is included on the score. Clearing feedback deletes the score. diff --git a/content/docs/configuration/librechat_yaml/example.mdx b/content/docs/configuration/librechat_yaml/example.mdx index c4d59b3a4..c47969fea 100644 --- a/content/docs/configuration/librechat_yaml/example.mdx +++ b/content/docs/configuration/librechat_yaml/example.mdx @@ -10,7 +10,7 @@ icon: FileCode This example config includes all documented endpoints (Except Azure, LiteLLM, MLX, and Ollama, which all require additional configurations) ```yaml filename="librechat.yaml" -version: 1.3.13 +version: 1.3.14 cache: true @@ -323,7 +323,7 @@ This example configuration file sets up LibreChat with detailed options across s # https://www.librechat.ai/docs/configuration/librechat_yaml # Configuration version (required) -version: 1.3.13 +version: 1.3.14 # Cache settings: Set to true to enable caching cache: true @@ -392,6 +392,10 @@ endpoints: # capabilities: ["code_interpreter", "retrieval", "actions", "tools", "image_vision"] # agents: # titleTiming: immediate # "immediate" (default) or "final" + # maxToolCallArgBytes: 65536 # 64 KiB per streamed tool call; 0 disables the global guard + # maxDeltaEventsPerTurn: 100000 # Optional event cap; omitted or 0 disables it + # maxToolCallArgBytesByTool: + # create_file: 131072 # Overrides the global limit for this tool; 0 disables its guard # skills: # maxCatalogSkills: 20 custom: @@ -522,11 +526,25 @@ endpoints: # messageFilter: # pii: # starterPatterns: [sk_prefix, bearer_header, api_key_header] +# # Custom patterns use RE2 syntax. Backreferences and lookaround are unsupported. +# # Invalid patterns are rejected when LibreChat loads the configuration. # customPatterns: # - id: anthropic_api_key # label: Anthropic API key # regex: "sk-ant-[A-Za-z0-9_-]{20,}" +# Speech, OCR, and web-search connections block private destinations at connect time. +# Use exact private host:port exemptions only for trusted self-hosted services. +# speech: +# tts: +# allowedAddresses: ['tts.internal:8080'] +# stt: +# allowedAddresses: ['stt.internal:8080'] +# ocr: +# allowedAddresses: ['ocr.internal:8080'] +# webSearch: +# allowedAddresses: ['searxng:8080'] + # fileConfig: # endpoints: # assistants: @@ -534,6 +552,7 @@ endpoints: # fileSizeLimit: 10 # Maximum size for an individual file in MB # totalSizeLimit: 50 # Maximum total size for all files in a single request in MB # supportedMimeTypes: +# # RE2 syntax: backreferences and lookaround are unsupported. # - "image/.*" # - "application/pdf" # openAI: diff --git a/content/docs/configuration/librechat_yaml/object_structure/actions.mdx b/content/docs/configuration/librechat_yaml/object_structure/actions.mdx index cddcb1509..aba57a16b 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/actions.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/actions.mdx @@ -40,6 +40,8 @@ actions: LibreChat includes SSRF (Server-Side Request Forgery) protection with the following behavior: +When an Action is created from OpenAPI metadata, LibreChat also verifies that the submitted Action domain matches the spec's server URL. If the submitted domain includes an explicit port, it must match the server URL's effective port (`443` for HTTPS or `80` for HTTP when the URL omits one). + **When `allowedDomains` is NOT configured:** - SSRF-prone targets are **blocked by default** - All other external domains are **allowed** diff --git a/content/docs/configuration/librechat_yaml/object_structure/agents.mdx b/content/docs/configuration/librechat_yaml/object_structure/agents.mdx index d2f8c8e47..349964f2d 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/agents.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/agents.mdx @@ -12,17 +12,33 @@ endpoints: agents: recursionLimit: 50 maxRecursionLimit: 100 + maxToolCallArgBytes: 65536 + maxDeltaEventsPerTurn: 100000 + maxToolCallArgBytesByTool: + create_file: 131072 disableBuilder: false # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below. - # Add "programmatic_tools" with "execute_code" to enable Programmatic Tool Calling for MCP tools. - # capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"] + # Opt-in capabilities: "programmatic_tools", "stateful_code_sessions", "run_in_background", and "tool_intents". + # capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "memory", "ask_user_question", "tools", "chain", "ocr"] # (optional) File citation configuration for file_search capability maxCitations: 30 # Maximum total citations in responses (1-50) maxCitationsPerFile: 7 # Maximum citations from each file (1-10) minRelevanceScore: 0.45 # Minimum relevance score threshold (0.0-1.0) titleTiming: immediate + activityLabel: true + activityModel: gpt-4.1-nano + activityPhaseLabel: true + activityPhaseMaxPerRun: 5 skills: maxCatalogSkills: 20 + toolApproval: + enabled: true + mode: default + deny: ['mcp:*:delete_*'] + ask: ['mcp:*:*'] + checkpointer: + type: mongo + ttl: 86400 remoteApi: auth: oidc: @@ -77,6 +93,51 @@ maxRecursionLimit: 100 For more information about agent steps, see [Max Agent Steps](/docs/features/agents#max-agent-steps). +## Stream circuit breakers + +These settings stop an Agent run when a provider stream appears to be producing runaway tool arguments or an unbounded sequence of delta events. + + + +LibreChat uses a 64 KiB global argument limit and ships a 128 KiB override for `create_file`, whose legitimate payloads are often larger. Entries in `maxToolCallArgBytesByTool` merge over that built-in override. If either guard trips, LibreChat aborts the in-flight provider stream and reports which limit was exceeded. + +```yaml filename="endpoints / agents / stream circuit breakers" +maxToolCallArgBytes: 65536 +maxDeltaEventsPerTurn: 100000 +maxToolCallArgBytesByTool: + create_file: 262144 + large_import: 524288 +``` + +To disable every argument-size guard, set both the global limit and the shipped `create_file` override to `0`: + +```yaml +maxToolCallArgBytes: 0 +maxToolCallArgBytesByTool: + create_file: 0 +``` + ## titleTiming -**Default:** `["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"]` +**Default:** `["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "memory", "ask_user_question", "tools", "chain", "ocr"]` -Programmatic Tool Calling is opt-in. Add `programmatic_tools` alongside `execute_code` only when your Code Interpreter deployment includes the Tool Call Server component. +`programmatic_tools`, `stateful_code_sessions`, `run_in_background`, and `tool_intents` are opt-in and must be added explicitly. Programmatic tools and stateful sessions also require `execute_code` and a compatible Code Interpreter deployment. Background code execution requires `run_in_background`, `execute_code`, and Code Interpreter. **Example:** @@ -182,13 +259,117 @@ capabilities: - 'actions' - 'context' - 'skills' + - 'memory' + - 'ask_user_question' - 'tools' - 'chain' - 'ocr' + # Optional: reuse one Code Interpreter workspace per conversation. + # - 'stateful_code_sessions' + # Optional: allow selected eligible MCP and Code Interpreter tools to run as background tasks. + # - 'run_in_background' + # Optional: show live model-written intent labels for native and selected MCP tools. + # - 'tool_intents' ``` **Note:** This field is optional. If omitted, the default behavior is to include all the capabilities listed in the default. +## toolApproval + +Controls human review for Agent tool calls. This feature is disabled by default. When enabled, matching calls pause until the user submits an allowed decision, such as approving, rejecting, or editing the arguments. + + + +Patterns use glob matching. MCP tools can be scoped with `mcp::`; for example, `mcp:github:*` matches every tool from the `github` server. Evaluation gives `deny` the highest priority, including in `bypass` mode. + +```yaml filename="endpoints / agents / toolApproval" +toolApproval: + enabled: true + mode: default + allow: + - 'mcp:analytics:read_*' + deny: + - 'mcp:*:delete_*' + ask: + - 'mcp:*:*' + reason: 'Review {tool} before it runs.' +``` + +Hooks are loaded once at server startup and execute in the LibreChat process. Each entry accepts a `module`, an optional tool-name `matcher` regex, and an optional `options` object passed to the module's builder. Only load code you trust. Per-role or tenant overrides do not reload hook modules; implement contextual behavior inside the hook. + +```yaml filename="endpoints / agents / toolApproval / hooks" +toolApproval: + enabled: true + hooks: + - module: '@acme/librechat-approval-hook' + matcher: '^mcp:production:' + options: + requireTicket: true +``` + +## checkpointer + +Configures storage for Agent runs paused by tool approval or Ask User. When either feature needs a checkpointer and this block is omitted, LibreChat uses the primary MongoDB with a 24-hour decision window. + + + +```yaml filename="endpoints / agents / checkpointer" +checkpointer: + type: mongo + ttl: 86400 +``` + +Use `type: memory` only for a single-process development deployment. A paused run stored in memory cannot resume after a restart or on another replica. + +MongoDB checkpoints log a warning when serialized state exceeds 8 MiB and reject a durable pause above 15 MiB, leaving headroom below MongoDB's 16 MiB document limit. Large inlined media or tool outputs are common causes; start a new conversation or reduce its context if a run reports `CHECKPOINT_TOO_LARGE`. + ## skills Controls endpoint-level Skills settings for agents. @@ -329,6 +510,7 @@ The `capabilities` field allows you to enable or disable specific functionalitie - **deferred_tools**: Allows agents to discover deferred MCP tools at runtime instead of loading every tool into context upfront. - **programmatic_tools**: Enables Programmatic Tool Calling for MCP tools marked Programmatic in the Agent Builder. Requires `execute_code` and a Code Interpreter deployment with the Tool Call Server component. This capability is opt-in and is not enabled by default. - **execute_code**: Allows the agent to execute code. +- **stateful_code_sessions**: Lets opted-in agents reuse one Code Interpreter workspace per conversation. Requires `execute_code`, a compatible Code Interpreter deployment, and the per-agent Advanced setting. This capability is highly experimental, is not enabled by default, and may change substantially during experimentation; do not treat its current behavior or configuration as a stable production contract. - **file_search**: Enables the agent to search and interact with files. When enabled, citation behavior is controlled by `maxCitations`, `maxCitationsPerFile`, and `minRelevanceScore` settings. - **web_search**: Enables web search functionality for agents, allowing them to search and retrieve information from the internet. - **artifacts**: Enables the agent to generate interactive artifacts (React components, HTML, Mermaid diagrams). @@ -336,9 +518,13 @@ The `capabilities` field allows you to enable or disable specific functionalitie - **actions**: Permits the agent to perform predefined actions. - **context**: Enables "Upload as Text" functionality in chat, and "File Context" for agents, allowing users to upload files and have their content extracted and included directly in the conversation. - **skills**: Enables Skills in the side panel, manual `$` invocation, model-invoked skills, and agent skill allowlists. See [Skills](/docs/features/skills). +- **memory**: Lets agents use `set_memory` and `delete_memory` when memory is configured and the user has access. Enabled by default; removed at runtime when memory is disabled. +- **ask_user_question**: Lets agents pause to ask one to four related questions in a single form and resume with the answers. Enabled by default. - **tools**: Grants the agent access to various tools. - **chain**: Enables Beta feature for agent chaining, also known as Mixture-of-Agents (MoA) workflows. - **ocr**: Optionally enhances "Upload as Text" in chat, and "File Context" for agents, allowing files to be uploaded and processed with OCR. **Requires an OCR service to be configured.** +- **run_in_background**: Makes Code Interpreter execution and shell tools background-eligible by default and enables per-tool background opt-in for MCP tools. An agent can explicitly opt Code Interpreter out. The setting permits background execution; the model decides per call whether to use it. Requires `execute_code` and a configured Code Interpreter deployment for code. This capability is not enabled by default. +- **tool_intents**: Adds live model-written intent labels to eligible tool calls. Native tools, including Code Interpreter tools, opt in automatically; MCP tools can be enabled individually or in bulk in the Agent Builder. Model specs use `describeIntent`. This capability is not enabled by default. By specifying the capabilities, you can control the features available to users when interacting with agents. @@ -359,6 +545,10 @@ endpoints: # Optional: enables Programmatic Tool Calling for MCP tools marked Programmatic in the Agent Builder. # - 'programmatic_tools' - 'execute_code' + # Optional: makes Code Interpreter background-eligible and enables selected MCP tools. + # - 'run_in_background' + # Optional: enables live intent labels for native and selected MCP tools. + # - 'tool_intents' - 'file_search' - 'skills' - 'subagents' @@ -376,6 +566,8 @@ In this example: - Only sources with 60%+ relevance are included - LibreChat Agents have access to code execution, file search (with citations), Skills, Subagents, actions, artifacts, file context, ocr services if configured, and web search capabilities - Programmatic Tool Calling remains disabled unless you add the `programmatic_tools` capability alongside `execute_code` +- Background tool calls remain disabled unless you add `run_in_background`; Code Interpreter tools then become eligible by default, while MCP tools still require per-tool selection +- Tool intent labels remain disabled unless you add `tool_intents`; native tools then opt in automatically, while MCP tools still require per-tool selection ## remoteApi diff --git a/content/docs/configuration/librechat_yaml/object_structure/anthropic_vertex.mdx b/content/docs/configuration/librechat_yaml/object_structure/anthropic_vertex.mdx index 334565bc0..82241c9b1 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/anthropic_vertex.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/anthropic_vertex.mdx @@ -32,16 +32,16 @@ endpoints: titleModel: "claude-3.5-haiku" # Use the visible model name (key from models config) vertex: - region: "us-east5" + region: "global" # serviceKeyFile: "/path/to/service-account.json" # Optional, defaults to api/data/auth.json # projectId: "${VERTEX_PROJECT_ID}" # Optional, auto-detected from service key # Model mapping: visible name -> Vertex AI deployment name models: - claude-opus-4.5: - deploymentName: claude-opus-4-5@20251101 - claude-sonnet-4: - deploymentName: claude-sonnet-4-20250514 + claude-opus-5: + deploymentName: claude-opus-5 + claude-sonnet-5: + deploymentName: claude-sonnet-5 claude-3.7-sonnet: deploymentName: claude-3-7-sonnet-20250219 claude-3.5-sonnet: @@ -70,14 +70,17 @@ The `vertex` object contains all Vertex AI-specific configuration options. **Default:** `us-east5` **Available Regions:** -- `global` (recommended for most use cases) + +- `global` +- `us` +- `eu` - `us-east5` - `us-central1` - `europe-west1` - `europe-west4` - `asia-southeast1` -> **Tip:** The `global` region is recommended as it provides automatic routing to the nearest available region. Use specific regions only if you have data residency requirements. +> **Important:** Claude Opus 4.7 and newer, Opus 5, Sonnet 5, and Fable/Mythos 5 require `global`, `us`, or `eu`. Specific regions such as `us-east5` serve Claude Sonnet 4.6 and earlier and return a model-not-found response for newer models. Use `global` for the broadest availability and no regional pricing premium, or `us`/`eu` when you need multi-region data residency. **Example:** ```yaml filename="endpoints / anthropic / vertex / region" @@ -122,6 +125,8 @@ serviceKeyFile: "/etc/secrets/gcp-service-account.json" The `models` field defines the available Claude models and maps user-friendly names to Vertex AI deployment IDs. This works similarly to [Azure OpenAI model mapping](/docs/configuration/librechat_yaml/object_structure/azure_openai#group-object-structure). +When `models` is omitted, LibreChat uses its built-in Vertex catalog and removes models incompatible with the configured `region`. An explicit `models` list or map is never filtered, so every deployment ID must be available in the selected location. + ### Format Options You can configure models in three ways: @@ -132,6 +137,8 @@ Use the actual Vertex AI model IDs directly. These will be shown as-is in the UI ```yaml filename="Simple array format" models: + - "claude-opus-5" + - "claude-sonnet-5" - "claude-sonnet-4-20250514" - "claude-3-7-sonnet-20250219" - "claude-3-5-haiku@20241022" @@ -143,10 +150,10 @@ Map user-friendly names to Vertex AI deployment names: ```yaml filename="Object format with custom names" models: - claude-opus-4.5: # Visible in UI - deploymentName: claude-opus-4-5@20251101 # Actual Vertex AI model ID - claude-sonnet-4: - deploymentName: claude-sonnet-4-20250514 + claude-opus-5: # Visible in UI + deploymentName: claude-opus-5 # Actual Vertex AI model ID + claude-sonnet-5: + deploymentName: claude-sonnet-5 claude-3.5-haiku: deploymentName: claude-3-5-haiku@20241022 ``` @@ -195,7 +202,7 @@ ANTHROPIC_VERTEX_REGION=global GOOGLE_SERVICE_KEY_FILE=/path/to/service-account.json ``` -> **Note:** When using environment variables, model mapping is not available. All known Claude models will be included automatically. +> **Note:** When using environment variables, model mapping is not available and LibreChat includes its standard Anthropic model catalog. Set `ANTHROPIC_VERTEX_REGION` to `global`, `us`, or `eu` before selecting a modern model that is unavailable from a specific region. --- @@ -209,14 +216,15 @@ Minimal configuration using defaults (Vertex AI is enabled by the presence of th endpoints: anthropic: vertex: - region: us-east5 + region: global ``` This uses: -- Region: `us-east5` + +- Region: `global` - Service key: `api/data/auth.json` (or `GOOGLE_SERVICE_KEY_FILE` env var) - Project ID: Auto-detected from service key -- Models: All known Claude models +- Models: LibreChat's built-in Vertex catalog for the selected location ### Production Setup with Model Mapping @@ -235,9 +243,9 @@ endpoints: models: opus: - deploymentName: claude-opus-4-5@20251101 + deploymentName: claude-opus-5 sonnet: - deploymentName: claude-sonnet-4-20250514 + deploymentName: claude-sonnet-5 haiku: deploymentName: claude-3-5-haiku@20241022 ``` @@ -265,6 +273,7 @@ You can only configure one region per deployment. For multi-region needs, consid **"Model not found"** - Check that the model ID in `deploymentName` is correct - Verify the model is available in your selected region +- Use `global`, `us`, or `eu` for Opus 4.7+, Opus 5, Sonnet 5, and Fable/Mythos 5 - Ensure the model is enabled in your Vertex AI Model Garden ### Region Issues @@ -276,9 +285,8 @@ You can only configure one region per deployment. For multi-region needs, consid **"Model not available in region"** - Not all Claude models are available in all regions -- Try switching to `global` region for automatic routing to an available region +- Switch to `global`, `us`, or `eu` for models newer than Sonnet 4.6 - Check the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to see which models are available in your region -- Consider using a different region that has broader model availability (e.g., `us-east5`) **Latency issues** - If you're experiencing high latency, try using a region geographically closer to your users diff --git a/content/docs/configuration/librechat_yaml/object_structure/config.mdx b/content/docs/configuration/librechat_yaml/object_structure/config.mdx index 66b6ae249..9e0b2c61b 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/config.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/config.mdx @@ -11,7 +11,7 @@ icon: Settings @@ -28,6 +28,43 @@ icon: Settings ]} /> +## langfuse + + + +**Subkeys:** + + + +Manage this object through **Settings โ†’ Langfuse** or an authorized administrator configuration client. The Settings flow verifies the connection and derives `projectId`; authorized administrator writes encrypt `secretKey`, generate `secretKeyPreview`, and redact the secret from reads. Plaintext `secretKey` values placed directly in `librechat.yaml` are not accepted by the runtime connection path. The legacy `displaySecretKey` and `fanout.enabled` fields are no longer part of the schema. + +`langfuse` is a base-configuration-only section. Role, group, and user configuration overrides cannot replace or tombstone it. + +See [Langfuse Configuration](/docs/configuration/langfuse) for availability rules, environment-managed credentials, and optional fanout deployment. + ## skillSync @@ -445,6 +488,12 @@ see: [OCR Config Object Structure](/docs/configuration/librechat_yaml/object_str 'Safe search filtering level. 0 = OFF, 1 = MODERATE (default), 2 = STRICT.', '', ], + [ + 'allowedAddresses', + 'Array of Strings', + 'Trusted private host:port exemptions for web search, scrape, and rerank connect-time SSRF checks. Public destinations remain available.', + '', + ], ]} /> @@ -782,7 +831,12 @@ see also: 'Specifies the number of recent messages to include in memory context.', '', ], - ['agent', 'Object | Union', 'Configures the agent responsible for memory processing.', ''], + [ + 'agent', + 'Object | Union', + 'Configures the optional automatic memory agent. Set `agent.enabled: true` to run it.', + '', + ], ]} /> @@ -841,6 +895,12 @@ see: [Memory Object Structure](/docs/configuration/librechat_yaml/object_structu 'Configures position-based tool result degradation for older messages.', '', ], + [ + 'retainRecent', + 'Object', + 'Preserves recent complete turns and/or tokens outside the generated summary.', + '', + ], ]} /> @@ -1258,6 +1318,8 @@ see: [MCP Servers Object Structure](/docs/configuration/librechat_yaml/object_st ]} /> +Both `speech.tts` and `speech.stt` accept an `allowedAddresses` array of trusted private host:port exemptions. Speech requests enforce the default private-address block at connect time. See the detailed [Speech reference](/docs/configuration/librechat_yaml/object_structure/speech#ssrf-protection) for entry rules, proxy behavior, and examples. + see: [Speech Object Structure](/docs/configuration/librechat_yaml/object_structure/speech) ## turnstile diff --git a/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx b/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx index 77874fe3a..9d2ba6d21 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/custom_endpoint.mdx @@ -106,6 +106,8 @@ or apiKey: 'user_provided' ``` +When a custom endpoint is written through the administrator configuration API, LibreChat encrypts a literal `apiKey` at rest and returns only an `apiKeyPreview`. `${ENV_VAR}` references and `user_provided` remain readable passthrough values. For endpoints defined directly in `librechat.yaml`, prefer an environment reference as shown above. + ## baseURL **Key:** @@ -146,6 +148,7 @@ baseURL: 'user_provided' - If the `baseURL` you set is the full completions endpoint, you can set the [directEndpoint](#directendpoint) field to `true` to use it directly. - This is necessary because the app appends "/chat/completions" or "/completion" to the `baseURL` by default. - When using [`provider: anthropic`](#provider), set `baseURL` to the API root that the Anthropic SDK should call, such as `https://api.anthropic.com` or your gateway root. LibreChat uses the native Anthropic `/v1/messages` path for that provider. +- On OpenAI-compatible custom endpoints, model IDs containing `claude` use Claude document restrictions: PDFs and text documents are accepted, while non-PDF binary document types are skipped before the request is sent. ## provider @@ -778,6 +781,8 @@ headers: **Note:** Supports dynamic environment variable values, which use the format: `"${VARIABLE_NAME}"`. +At the final outbound resolution step, recognized `{{LIBRECHAT_USER_*}}`, `{{LIBRECHAT_BODY_*}}`, and `{{LIBRECHAT_OPENID_*}}` placeholders without a value become empty strings instead of being forwarded as template text. Unknown placeholder names remain unchanged so configuration typos are visible. + When `models.fetch: true` is used, these headers are also resolved and forwarded to the model-list request for admin-controlled base URLs. A configured `Authorization` header takes precedence over the endpoint `apiKey` fallback, which is useful for auth-aware proxies that return per-user model lists. If `baseURL: "user_provided"` is configured, LibreChat does not forward configured header templates to the user-provided destination. For `provider: anthropic`, headers are forwarded through the native Anthropic client instead of the OpenAI-compatible client. **Available User Field Placeholders:** @@ -801,6 +806,7 @@ When `models.fetch: true` is used, these headers are also resolved and forwarded | `{{LIBRECHAT_USER_EMAILVERIFIED}}` | `emailVerified` | Boolean โ†’ String | Email verification status ("true" or "false") | | `{{LIBRECHAT_USER_TWOFACTORENABLED}}` | `twoFactorEnabled` | Boolean โ†’ String | 2FA status ("true" or "false") | | `{{LIBRECHAT_USER_TERMSACCEPTED}}` | `termsAccepted` | Boolean โ†’ String | Terms acceptance status ("true" or "false") | +| `{{LIBRECHAT_USER_TERMSACCEPTEDAT}}` | `termsAcceptedAt` | Date โ†’ String | Terms acceptance timestamp | **Available Request Body Placeholders:** diff --git a/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx b/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx index cb8f6abba..40f3e5789 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx @@ -37,6 +37,7 @@ There are 8 main fields under `fileConfig`: - `YourCustomEndpointName` - You can omit values, in which case, the app will use the default values as defined per endpoint type listed below. - LibreChat counts 1 megabyte as follows: `1 x 1024 x 1024` +- Long-running upload response streaming and server-side remote URL fetch limits are configured with the [`FILE_UPLOAD_SSE_ENABLED`, `REMOTE_FILE_FETCH_TIMEOUT_MS`, and `REMOTE_FILE_FETCH_MAX_BYTES` environment variables](/docs/configuration/dotenv#file-uploads). ## Example @@ -69,7 +70,7 @@ fileConfig: supportedMimeTypes: - "^image/(jpeg|gif|png|webp|heic|heif)$" - "^application/pdf$" - - "^application/vnd\\.openxmlformats-officedocument\\.(wordprocessingml\\.document|presentationml\\.presentation|spreadsheetml\\.sheet)$" + - "^application/vnd\\.openxmlformats-officedocument\\.(wordprocessingml\\.document|presentationml\\.(presentation|template)|spreadsheetml\\.sheet)$" - "^application/vnd\\.ms-(word|powerpoint|excel)$" - "^application/epub\\+zip$" text: @@ -80,6 +81,10 @@ fileConfig: - "^audio/(mp3|mpeg|mpeg3|wav|wave|x-wav|ogg|vorbis|mp4|x-m4a|flac|x-flac|webm)$" ``` + + LibreChat evaluates administrator-configured `supportedMimeTypes` patterns on the server with an RE2-compatible, linear-time regular expression engine. Backreferences and lookaround are not supported. Invalid patterns are logged and skipped; if every pattern in a configured list is invalid, that list fails closed and rejects every file instead of becoming unrestricted. + + ## serverFileSizeLimit -**Default:** All text files and common programming languages +**Default:** All text files, common programming languages, and `.eml` email files ```yaml filename="fileConfig / text / supportedMimeTypes" fileConfig: @@ -392,3 +397,5 @@ assistants: - "image/.*" - "application/pdf" ``` + +LibreChat normalizes common MIME aliases before applying these patterns. In particular, `application/x-shellscript` (reported by Chrome on Linux) and `text/x-shellscript` (reported by libmagic) become `application/x-sh`. A custom allowlist that accepts shell scripts should therefore permit the canonical `application/x-sh` type. Rejected uploads return the reported unsupported type to the client instead of a generic server error. diff --git a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx index 7cb10ade9..69ba56ba5 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx @@ -298,6 +298,8 @@ interface: ]} /> +When modal acceptance is enabled, LibreChat records both the acceptance state and the time it was accepted. After upgrading an existing deployment, run `npm run migrate:terms-timestamp` to backfill accepted users that do not have a timestamp. The migration asks for confirmation, processes all tenants, uses each user's account creation time as the fallback, and exits non-zero if any batch fails. Running `npm run reset-terms` clears both the acceptance state and its timestamp so users must accept again. + ## modelSelect **Key:** @@ -1096,7 +1098,7 @@ interface: Enables/disables the web search button in the chat interface. More info on [Web Search Configuration](/docs/configuration/librechat_yaml/object_structure/web_search) -**Note:** This setting does not disable the [Agents Web Search Capability](/docs/features/agents#web-search). To disable the Agents Capability, see the [Agents Endpoint configuration](/docs/configuration/librechat_yaml/object_structure/agents) instead. +**Note:** This setting does not disable the [Agents Web Search capability](/docs/features/agents#agent-capabilities). To disable the Agents capability, see the [Agents endpoint configuration](/docs/configuration/librechat_yaml/object_structure/agents#capabilities) instead. > **Deprecated for permission management.** Seeds the `WEB_SEARCH` role permission at startup for the default `USER` role only. Prefer the [Admin Panel](/docs/features/admin_panel). diff --git a/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx b/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx index 81c5b8237..fb7ea6c41 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx @@ -91,6 +91,14 @@ mcpServers: ]} /> + + Model-facing tool keys preserve letters, numbers, `_`, `.`, and `-`; other characters in a server + name are replaced with `_`. LibreChat maps those normalized keys back to the configured name and + heals older saved Agent tool references. Avoid two names that normalize to the same value, such as + `Sales Force` and `Sales:Force`: their tool keys are ambiguous, so LibreChat warns and excludes the + shadowed server's tools rather than risk routing a call to the wrong server. + + ### Subkeys +## allowedDomains + ### Security Context (SSRF Protection) LibreChat includes SSRF (Server-Side Request Forgery) protection with the following behavior: diff --git a/content/docs/configuration/librechat_yaml/object_structure/memory.mdx b/content/docs/configuration/librechat_yaml/object_structure/memory.mdx index 12166c734..e241ffb4a 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/memory.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/memory.mdx @@ -19,6 +19,7 @@ memory: personalize: true messageWindowSize: 5 agent: + enabled: true provider: 'openAI' model: 'gpt-4' instructions: 'You are a helpful assistant that remembers user preferences and context.' @@ -178,12 +179,29 @@ memory: [ 'agent', 'Object | Union', - 'Configures the agent responsible for memory processing. Can be either a reference to an existing agent by ID or a complete agent configuration.', - 'agent: { provider: "openAI", model: "gpt-4" }', + 'Configures the optional automatic memory agent. Can be either a reference to an existing agent by ID or a complete agent configuration.', + 'agent: { enabled: true, provider: "openAI", model: "gpt-4" }', ], ]} /> +Automatic extraction is opt-in. Set `agent.enabled: true` in either configuration format below. Omitting `enabled`, or setting it to `false`, keeps manual memory and Agent memory tools available without running the automatic memory agent on chat requests. + +### enabled + + + +**Default:** `false` + The `agent` field supports two different configuration formats: ### Agent by ID @@ -193,6 +211,7 @@ When you have a pre-configured agent, you can reference it by its ID: ```yaml filename="memory / agent (by ID)" memory: agent: + enabled: true id: 'memory-agent-001' ``` @@ -203,6 +222,7 @@ For more control, you can define a complete agent configuration: ```yaml filename="memory / agent (custom)" memory: agent: + enabled: true provider: 'openAI' model: 'gpt-4' instructions: 'You are a memory assistant that helps maintain conversation context and user preferences.' @@ -268,7 +288,7 @@ When using custom agent configuration, the following fields are available: Here's a comprehensive example showing all memory configuration options: ```yaml filename="librechat.yaml" -version: 1.3.10 +version: 1.3.14 cache: true memory: @@ -284,6 +304,7 @@ memory: personalize: true messageWindowSize: 8 agent: + enabled: true provider: 'openAI' model: 'gpt-4' instructions: | @@ -330,6 +351,7 @@ memory: personalize: true messageWindowSize: 10 agent: + enabled: true provider: 'Custom Memory Endpoint' model: 'gpt-4o-mini' ``` @@ -344,6 +366,7 @@ memory: - `maxInputTokens` bounds the chat context sent to the automatic memory agent, while `tokenLimit` controls stored memory usage - Valid keys provide granular control over what information can be stored - Custom `instructions` replace default memory handling instructions and should be used with `validKeys` -- Agent configuration allows customization of memory processing behavior +- `agent.enabled: true` is required for automatic memory extraction +- Agent configuration allows customization of automatic memory processing behavior - When disabled, all memory features are turned off regardless of other settings - The message window size affects how much recent context is considered for memory updates diff --git a/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx b/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx index 6c34ca6cc..6ca7c577b 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx @@ -5,7 +5,7 @@ icon: ShieldAlert ## Overview -The `messageFilter` object configures server-side message filters. In v1.3.13, the supported filter type is `messageFilter.pii`. +The `messageFilter` object configures server-side message filters. The supported filter type is `messageFilter.pii`. `messageFilter.pii` rejects submitted message text that matches credential-shaped starter patterns or operator-defined regular expressions before the text reaches moderation, a model request, or message persistence. @@ -65,12 +65,14 @@ messageFilter: [ 'regex', 'String', - 'JavaScript-flavor regular expression. LibreChat validates it at config load time and compiles it with the global flag.', + 'RE2 regular expression. LibreChat validates it at config load time and applies it globally.', "regex: 'sk-ant-[A-Za-z0-9_-]{20,}'", ], ]} /> +Custom patterns use the linear-time RE2 engine. Backreferences and lookaround are not supported, and some escapes differ from JavaScript regular expressions. LibreChat rejects patterns that RE2 cannot compile when loading the configuration. + ## Behavior When submitted message text matches a configured PII pattern, LibreChat returns HTTP `400` with `message_filter_pii_block` and a message asking the caller to remove the matched credential type. diff --git a/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx b/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx index f6297749e..c7498b637 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/model_specs.mdx @@ -252,6 +252,8 @@ Specifies a first-run default without overriding a user's later selections. Use Viewing an older conversation that used a soft-default spec does not re-arm that spec as the user's default after they have made another selection. +If the user's stored selection points to an Agent that no longer resolves, LibreChat re-arms the soft default so a new chat still has a usable selection. A temporary failure to load the Agent list does not clear the stored choice or trigger that fallback. + **Example:** ```yaml filename="modelSpecs / softDefault" @@ -267,6 +269,34 @@ modelSpecs: --- +### showInMenu + + + +Set `showInMenu: false` to hide a spec from interactive selection while keeping it available for trusted server-side callers that explicitly send its `name` in the `spec` field. This differs from `showIconInMenu`, which hides only the icon. + +```yaml filename="modelSpecs / showInMenu" +modelSpecs: + list: + - name: 'api-only-assistant' + label: 'API-only Assistant' + showInMenu: false + preset: + endpoint: 'openAI' + model: 'gpt-4o-mini' +``` + +--- + ### iconURL + +Requires configured [User Memory](/docs/features/memory), the endpoint-level `memory` capability, and user memory permissions. When enabled, the model can save or delete structured memories when the user explicitly requests it. + +```yaml filename="modelSpecs / memory" +modelSpecs: + list: + - name: 'memory-assistant' + memory: true + preset: + endpoint: 'openAI' + model: 'gpt-4o-mini' +``` + +--- + +### askUserQuestion + + + +Requires the endpoint-level `ask_user_question` capability. This is supported in Agent chat runs that provide LibreChat's durable pause/resume flow. + +```yaml filename="modelSpecs / askUserQuestion" +modelSpecs: + list: + - name: 'interactive-assistant' + askUserQuestion: true + preset: + endpoint: 'openAI' + model: 'gpt-4o-mini' +``` + +--- + +### runInBackground + + + +Requires the opt-in endpoint-level `run_in_background` capability. With that capability and `executeCode: true`, Code Interpreter execution and shell calls are background-eligible by default. Set `runInBackground: false` or `[]` to opt them out, `true` to enable every eligible tool attached to the spec, or an array of resolved tool IDs to enable only those tools. Selecting `execute_code` or `bash_tool` selects both native code tools; a list that omits them opts them out. Unsupported or misspelled selections are logged. + +The model can start an eligible tool, continue working, and poll with `check_background_task`. Completed code output and generated files are attached to the original code call. Background task state is process-local and does not survive a server restart or move across replicas. + +```yaml filename="modelSpecs / runInBackground" +modelSpecs: + list: + - name: 'operations-assistant' + mcpServers: ['operations'] + executeCode: true + runInBackground: + - 'execute_code' + - 'slow_report_mcp_operations' + preset: + endpoint: 'openAI' + model: 'gpt-4o-mini' +``` + +--- + +### describeIntent + + + +Requires the opt-in endpoint-level `tool_intents` capability. Native tools such as web search, file authoring, memory, and supported Code Interpreter tools use intent labels by default while the capability is enabled. Set `describeIntent: true` to enable every eligible tool, or provide resolved tool IDs to enable only those tools and disable labels for everything else. An empty array disables all intent labels for the spec. Omitting the field or setting it to `false` adds no broader selection, so native defaults still apply. + +Intent labels are included in tool schemas and therefore add schema tokens to model requests. LibreChat logs selections that are misspelled, unavailable to the spec, or ineligible. + +```yaml filename="modelSpecs / describeIntent" +modelSpecs: + list: + - name: 'research-assistant' + webSearch: true + mcpServers: ['research'] + describeIntent: + - 'web_search' + - 'search_mcp_research' + preset: + endpoint: 'openAI' + model: 'gpt-4o-mini' +``` + +--- + ### mcpServers **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like), `bedrock` (ZAI, MoonshotAI models) @@ -1441,7 +1592,7 @@ preset: [ 'reasoning_effort', 'String', - 'Controls the reasoning effort level for the model. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning. The `xhigh` option provides maximum reasoning capability for complex problems. For Bedrock, accepted values are `low`, `medium`, `high`.', + 'Controls the reasoning effort level for the model. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning. Supported OpenAI models may expose `xhigh` and `max`; for Bedrock, accepted values are `low`, `medium`, `high`.', '', ], ]} @@ -1486,6 +1637,62 @@ preset: --- +#### reasoning_mode + +**Accepted Values:** + +- `""` (empty string - unset) +- `"standard"` +- `"pro"` + +> **Supported by:** OpenAI Responses API models that expose reasoning mode, including GPT-5.6 + + + +```yaml +preset: + reasoning_effort: 'high' + reasoning_mode: 'pro' +``` + +--- + +#### reasoning_context + +**Accepted Values:** + +- `""` (empty string - unset) +- `"auto"` +- `"current_turn"` +- `"all_turns"` + +> **Supported by:** OpenAI Responses API models that expose reasoning context, including GPT-5.6 + + + +```yaml +preset: + reasoning_effort: 'high' + reasoning_context: 'all_turns' +``` + +For GPT-5.6, LibreChat defaults reasoning requests to the Responses API unless `useResponsesApi: false` is set explicitly. + +--- + #### useResponsesApi > **Supported by:** `openAI`, `azureOpenAI`, custom (OpenAI-like) diff --git a/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx b/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx index b6f6c3c29..d73cc51e4 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx @@ -7,12 +7,13 @@ icon: ScanText The `ocr` object allows you to configure Optical Character Recognition (OCR) settings for the application, enabling the extraction of text from images. This section provides a detailed breakdown of the `ocr` object structure. -There are 4 main fields under `ocr`: +There are 5 main fields under `ocr`: - `mistralModel` - `apiKey` - `baseURL` - `strategy` + - `allowedAddresses` **Notes:** @@ -64,6 +65,7 @@ Example with custom OCR: ocr: apiKey: "your-custom-ocr-api-key" baseURL: "https://your-custom-ocr-service.com/api" + allowedAddresses: ["ocr.internal:8080"] strategy: "custom_ocr" ``` @@ -145,6 +147,27 @@ ocr: baseURL: "https://your-ocr-service.com/api" ``` +## allowedAddresses + + + +## allowedAddresses + +OCR requests block private, loopback, link-local, and cloud-metadata destinations at connect time and disable redirects. `allowedAddresses` is an exemption list for exact trusted private `host:port`, `private.ip:port`, or `[ipv6]:port` targets; it does not restrict access to public destinations. + + + Use `allowedAddresses` only for a private OCR service you control. An exempted hostname trusts whatever private address it resolves to on that port, so prefer a private IP literal when possible. With a forward proxy, the proxy must enforce destination SSRF policy; literal private destinations remain blocked unless explicitly exempted. + + ## strategy diff --git a/content/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings.mdx b/content/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings.mdx index c9b722f30..7d7c53754 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings.mdx @@ -44,7 +44,7 @@ endpoints: titleEndpoint: 'anthropic' google: - streamRate: 1 + streamRate: 25 titleModel: 'gemini-2.0-flash-lite' titlePromptTemplate: "Human: {input}\nAssistant: {output}" headers: @@ -56,6 +56,15 @@ endpoints: azureAssistants: streamRate: 30 + agents: + activityLabel: true + activityEndpoint: 'openAI' + activityModel: 'gpt-4.1-nano' + activityMaxPerRun: 20 + activityCharLimit: 600 + activityPhaseLabel: true + activityPhaseMaxPerRun: 5 + # Global configuration using 'all' - this applies shared settings across endpoints. # Most defined values override endpoint defaults; headers are merged and endpoint values win on collisions. all: @@ -72,7 +81,7 @@ endpoints: {convo} ``` -> **Important:** When using the `all` configuration, most shared properties you define apply across endpoints. In the example above, the `all` configuration would apply `titleConvo`, `titleModel`, and `titlePrompt` to all endpoints, while individual `streamRate` settings would be preserved since it's not defined in `all`. `headers` are merged separately: values from `endpoints.all.headers` apply globally, and endpoint-level headers win on key collisions. +> **Important:** When using the `all` configuration, most shared properties you define apply across endpoints. In the example above, the `all` configuration would apply `titleConvo`, `titleModel`, and `titlePrompt` to all endpoints, while individual `streamRate` settings would be preserved since it's not defined in `all`. `headers` are merged separately: values from `endpoints.all.headers` apply globally, and endpoint-level headers win on key collisions. Activity settings resolve field by field in the same order, so an unrelated `all` setting does not hide an endpoint's activity configuration. ## streamRate @@ -89,9 +98,11 @@ endpoints: ]} /> -**Default:** 1 +**Default:** Provider-dependent. OpenAI, custom endpoints, Anthropic, Google, Bedrock, and Agents SDK-backed streams use adaptive smoothing with a 25 ms target. Legacy Assistants and Ollama handlers retain their per-provider-chunk behavior, with a 1 ms default. + +Adaptive smoothing emits the first text token without delay, increases chunk size when a stream falls behind, and preserves tool-call and metadata ordering. Set `streamRate` to a non-negative millisecond target; `streamRate: 0` disables adaptive smoothing on the SDK-backed providers listed above. -> Allows for streaming data at the fastest rate possible while allowing the system to wait for the next tick +An endpoint-specific value is preserved when `endpoints.all` exists without `streamRate`. Defining `endpoints.all.streamRate` overrides endpoint values, including an explicit `0`. ## titleConvo @@ -300,6 +311,99 @@ endpoints: # Will use anthropic's configuration for title generation ``` +## Agent Activity Groups + +Activity groups make long Agent runs easier to scan by collapsing each contiguous block of reasoning and tool calls under a generated one-line header. Header generation runs outside the main model-response path, but it is still a model call and its usage is recorded and billed. + +With parent phase labels enabled, short progress text stays inside the active phase. A phase closes before substantial answer text so the result remains outside the collapsed summary, and a later block of reasoning or tool calls can begin another phase in the same run. LibreChat also rebases saved phase boundaries when malformed or omitted content is compacted, preserving their alignment after reload. + + + +```yaml filename="endpoints / agents / activity groups" +endpoints: + agents: + activityLabel: true + activityEndpoint: 'openAI' + activityModel: 'gpt-4.1-nano' + activityMaxPerRun: 20 + activityCharLimit: 600 + activityPhaseLabel: true + activityPhaseMaxPerRun: 5 +``` + +You can also set these fields under `endpoints.all` or a backing provider/custom endpoint. Values resolve independently, with the first defined value winning in this order: `endpoints.all`, the public `agents` endpoint, then the backing provider or custom endpoint. If `activityEndpoint` is unknown, LibreChat logs a warning and uses the Agent's provider instead. + +Parent phase summaries are independent of child activity labels: `activityPhaseLabel` can be enabled with or without `activityLabel`. LibreChat spends a phase-summary model call only for a phase containing at least two logical activities. `activityCharLimit` also bounds the evidence used for phase summaries. Phase model selection resolves through `activityPhaseModel`, `activityModel`, the originating endpoint's `titleModel`, then the current run model; phase endpoint selection resolves through `activityPhaseEndpoint`, `activityEndpoint`, then the Agent provider. An unknown configured phase endpoint logs a warning and falls back to the Agent provider. + ## maxToolResultChars **Key:** @@ -362,6 +466,7 @@ endpoints: **Notes:** - Values support `${ENV_VAR}`, `{{LIBRECHAT_USER_*}}`, and request-body placeholders such as `{{LIBRECHAT_BODY_CONVERSATIONID}}`. +- At the final outbound resolution step, recognized user, request-body, and OpenID placeholders without a value become empty strings instead of being forwarded as template text. Unknown placeholder names remain unchanged so configuration typos are visible. - Endpoint-level headers override `endpoints.all.headers` on key collisions. - Provider-managed auth and required beta/protocol headers remain authoritative. Anthropic beta values are merged so custom beta flags do not clobber required provider flags. - Headers are also forwarded for supported provider model-list requests. @@ -375,7 +480,7 @@ endpoints: - When using the `all` configuration, it will override the corresponding settings in ALL individual endpoints - The `all` key does not accept `baseURL` - Settings not defined in `all` will preserve their individual endpoint values -- For `streamRate`: Recommended values are between 25-40 for a smooth streaming experience +- For `streamRate`: Values between 25-40 are recommended where endpoint-specific smoothing is desired - Using a higher stream rate is a must when serving the app to many users at scale **Example of Override Behavior:** diff --git a/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx b/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx index fb50adce5..be9e4acbe 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx @@ -134,8 +134,13 @@ GitHub Skill Sync: - Stores source metadata such as source id, owner, repo, ref, skill path, commit SHA, and blob SHA. - Updates mirrored Skills when the upstream file changes. - Deletes mirrored Skills and files that were removed from the configured source. +- Validates and publishes Skills independently, so one invalid or conflicting Skill does not hide valid Skills from the same source. +- Preserves a skipped Skill's last-known-good mirror and rolls back incomplete writes for that Skill. +- Marks a run `partial` when it publishes at least one Skill but skips another, and records a bounded skipped count and details for administrator status reads. - Uses a sync lock so only one GitHub sync run proceeds at a time. +Unknown `SKILL.md` frontmatter keys are accepted when their values remain within the bounded, JSON-safe extension limits. Invalid recognized fields, unsafe extension values, duplicate names, and ownership conflicts skip only the affected Skill. Authentication, rate-limit, lock-loss, repository access, and rollback failures remain source-level failures. + ## Admin Endpoints The admin API exposes GitHub Skill Sync status, manual runs, and stored credential management: @@ -145,7 +150,7 @@ The admin API exposes GitHub Skill Sync status, manual runs, and stored credenti [ 'GET /api/admin/skills/sync/status', 'Endpoint', - 'Returns enabled state, schedule settings, source status, credential presence, and recent sync counts.', + 'Returns enabled state, schedule settings, source status, credential presence, recent sync counts, and bounded skipped-Skill details for partial runs.', '', ], [ diff --git a/content/docs/configuration/librechat_yaml/object_structure/speech.mdx b/content/docs/configuration/librechat_yaml/object_structure/speech.mdx index d6abd1b89..8931152f3 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/speech.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/speech.mdx @@ -24,6 +24,7 @@ The `speech` object allows you to configure Text-to-Speech (TTS) and Speech-to-T ```yaml filename="speech" speech: tts: + allowedAddresses: ["tts.internal:8080"] openai: apiKey: "${TTS_API_KEY}" model: "tts-1" @@ -33,6 +34,7 @@ speech: model: "eleven_multilingual_v2" voices: ["voice-id-1", "voice-id-2"] stt: + allowedAddresses: ["stt.internal:8080"] openai: apiKey: "${STT_API_KEY}" model: "whisper-1" @@ -45,10 +47,33 @@ speech: --- +## SSRF Protection + +LibreChat guards operator-provided STT and TTS URLs at connect time. Private, loopback, link-local, and cloud-metadata destinations are blocked by default, and redirects are disabled for speech requests. + +`speech.tts.allowedAddresses` and `speech.stt.allowedAddresses` are separate exemption lists, not strict allowlists. Add an exact private `host:port`, `private.ip:port`, or `[ipv6]:port` only when that section must reach a trusted self-hosted service. Do not use a URL, path, CIDR range, bare host/IP, or public IP literal. Default ports are normalized, so an HTTPS URL without an explicit port is checked as port `443`. + +An exempted hostname trusts whatever private address it resolves to on that port. Prefer a private IP literal when possible, and list only names whose DNS you control and which cannot be repointed by an attacker. + +When a forward proxy carries a hostname request, the proxy performs destination DNS and egress, so the proxy must enforce its own SSRF policy. A literal private destination is still blocked before proxy handling unless its exact address and port are exempted. + +--- + ## tts The `tts` object configures Text-to-Speech providers. Multiple providers can be configured, and users can choose which one to use. + + ### openai OpenAI TTS configuration using models like `tts-1` or `tts-1-hd`. @@ -165,6 +190,17 @@ tts: The `stt` object configures Speech-to-Text providers. + + ### openai OpenAI Whisper STT configuration. @@ -229,7 +265,12 @@ When using an object instead of a boolean: + +```yaml filename="summarization / retainRecent" +summarization: + retainRecent: + turns: 2 + tokens: 2000 +``` + +Both fields are optional. Omit `retainRecent` to use the Agents SDK's normal compaction behavior. + ## contextPruning `. Browser RUM proxy outcomes are reported as `rum_proxy_requests_total{endpoint,result}`, where `endpoint` is `traces`, `logs`, or `unknown`, and `result` can be `success`, `auth_drop`, `auth_error`, `bad_request`, `not_configured`, `collector_4xx`, `collector_5xx`, `collector_error`, or `collector_timeout`. +## Built-in API Metrics + +LibreChat exposes Prometheus metrics from the API server at `/metrics`. Set `METRICS_SECRET` and scrape the endpoint with `Authorization: Bearer `. The endpoint returns `401` when the secret is unset, the header is missing, or the token does not match. + +```yaml filename="prometheus.yml" +scrape_configs: + - job_name: librechat-api + scheme: https + metrics_path: /metrics + authorization: + type: Bearer + credentials: your-metrics-secret + static_configs: + - targets: ['librechat.example.com'] +``` + +### Agent Startup Metrics + +Initial Agent chat requests emit two startup metrics: + +- `agent_startup_milestone_duration_seconds{milestone}` measures cumulative latency from request ingress to each startup milestone. +- `agent_startups_total{result}` counts startup attempts by terminal result. + +Milestones cover request admission, job creation and acknowledgement, conversation and history loading, client and run initialization, stream startup, and the first queued response or content event. Results distinguish content queued, completion without a content delta, deduplication, rejection, pause, replacement, abort, and error. + +When [backend OpenTelemetry tracing](/docs/configuration/dotenv#opentelemetry-tracing) is enabled, the `librechat.agent.startup` span reports the same milestones as events. It includes total startup duration, milestone count, terminal result, and the generation stream ID when one is assigned. + +### Redis Metrics + +Redis-backed caches and services emit two logical-operation metrics: + +- `redis_operations_total{client,use_case,operation,status}` counts operations. +- `redis_operation_duration_seconds{client,use_case,operation,status}` measures latency. + +`client` is `keyv` or `ioredis`, and `status` is `success` or `error`. Bounded `use_case` labels identify work such as caches, sessions, rate limits, concurrency, ACL principals, resumable stream jobs and pub/sub, MCP registry scans, and leader election. These metrics count LibreChat's logical operations rather than every internal Redis round trip. Connection lifecycle pings and global maintenance are excluded, and clearing a namespace is counted as one logical operation. + +When [backend OpenTelemetry tracing](/docs/configuration/dotenv#opentelemetry-tracing) is enabled, each HTTP span also summarizes its Redis work with: + +- `librechat.redis.calls` +- `librechat.redis.duration_ms` +- `librechat.redis.errors` +- `librechat.redis.max_call_ms` +- `librechat.redis.operations` +- `librechat.redis.use_cases` + +The ten use cases with the highest total duration also receive `calls`, `duration_ms`, `errors`, and `max_call_ms` attributes under `librechat.redis..*`. This request-level summary does not require command-level Redis spans; enable `OTEL_IOREDIS_TRACING_ENABLED` only when individual command spans are needed. + +### Browser RUM Proxy Metrics + +Browser RUM proxy outcomes are reported as `rum_proxy_requests_total{endpoint,result}`. `endpoint` is `traces`, `logs`, or `unknown`; `result` can be `success`, `auth_drop`, `auth_error`, `bad_request`, `not_configured`, `collector_4xx`, `collector_5xx`, `collector_error`, or `collector_timeout`. + +## Database Metrics Exporter The metrics exporter is available at [virtUOS/librechat_exporter](https://github.com/virtUOS/librechat_exporter). It is a separate tool you deploy alongside LibreChat. diff --git a/content/docs/configuration/pre_configured_ai/anthropic.mdx b/content/docs/configuration/pre_configured_ai/anthropic.mdx index b9133d1df..e81f73472 100644 --- a/content/docs/configuration/pre_configured_ai/anthropic.mdx +++ b/content/docs/configuration/pre_configured_ai/anthropic.mdx @@ -14,12 +14,14 @@ ANTHROPIC_API_KEY=user_provided - You can determine which models you would like to have available with `ANTHROPIC_MODELS`. ```bash filename=".env" -ANTHROPIC_MODELS=claude-fable-5,claude-opus-4-8,claude-opus-4-7,claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-20250514,claude-3-7-sonnet-20250219,claude-3-5-sonnet-20241022,claude-3-5-haiku-20241022 +ANTHROPIC_MODELS=claude-fable-5,claude-opus-5,claude-opus-4-8,claude-opus-4-7,claude-sonnet-5,claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-20250514,claude-3-7-sonnet-20250219,claude-3-5-sonnet-20241022,claude-3-5-haiku-20241022 ``` **Notes:** - Claude Fable 5 is included in LibreChat's default Anthropic model catalog. Fable/Mythos-class models use the modern Anthropic profile in LibreChat: 1M context, 128K max output, adaptive thinking, prompt caching, and `thinkingDisplay` support for summarized or omitted reasoning output. +- Claude Opus 5 is available through direct Anthropic, Anthropic on Vertex AI, and AWS Bedrock. It has a 1M-token context window and 128K-token maximum output. Adaptive thinking is enabled unless explicitly disabled; when disabled, LibreChat limits `xhigh` or `max` effort to `high` to keep requests valid. +- Claude Sonnet 5 is available through direct Anthropic, Anthropic on Vertex AI, and AWS Bedrock. LibreChat assigns it a 1M-token context window and 128K-token maximum output, uses adaptive thinking with summarized display when thinking is enabled, and sends an explicit disabled setting when a user turns thinking off. - Anthropic endpoint supports all [Shared Endpoint Settings](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings) via the `librechat.yaml` configuration file, including `streamRate`, `headers`, `titleModel`, `titleMethod`, `titlePrompt`, `titlePromptTemplate`, and `titleEndpoint` - To configure Anthropic or an Anthropic-compatible gateway as a separate custom endpoint, use [`provider: "anthropic"`](/docs/configuration/librechat_yaml/object_structure/custom_endpoint#provider). @@ -42,7 +44,8 @@ Set the following environment variables to enable Anthropic via Vertex AI: ANTHROPIC_USE_VERTEX=true # Vertex AI region (optional, defaults to 'us-east5') -# Available regions: global, us-east5, us-central1, europe-west1, europe-west4, asia-southeast1 +# Modern models such as Opus 5 require global, us, or eu. +# Specific regions serve Sonnet 4.6 and earlier. ANTHROPIC_VERTEX_REGION=global # Path to Google service account key file (optional) @@ -67,12 +70,12 @@ For model name mapping and advanced settings (similar to Azure OpenAI configurat endpoints: anthropic: vertex: - region: us-east5 + region: global models: - claude-opus-4.5: - deploymentName: claude-opus-4-5@20251101 - claude-sonnet-4: - deploymentName: claude-sonnet-4-20250514 + claude-opus-5: + deploymentName: claude-opus-5 + claude-sonnet-5: + deploymentName: claude-sonnet-5 claude-3.5-haiku: deploymentName: claude-3-5-haiku@20241022 ``` diff --git a/content/docs/configuration/pre_configured_ai/bedrock.mdx b/content/docs/configuration/pre_configured_ai/bedrock.mdx index 9837b8e9f..04ad5a0b5 100644 --- a/content/docs/configuration/pre_configured_ai/bedrock.mdx +++ b/content/docs/configuration/pre_configured_ai/bedrock.mdx @@ -84,12 +84,16 @@ For AWS credential behavior details, see the [AWS SDK for JavaScript credential - You can optionally specify which models you want to make available with `BEDROCK_AWS_MODELS`: ```bash filename=".env" -BEDROCK_AWS_MODELS=anthropic.claude-fable-5,anthropic.claude-opus-4-8,anthropic.claude-opus-4-7,anthropic.claude-sonnet-4-6,meta.llama3-1-8b-instruct-v1:0 +BEDROCK_AWS_MODELS=global.anthropic.claude-fable-5,global.anthropic.claude-opus-5,global.anthropic.claude-opus-4-8,global.anthropic.claude-opus-4-7,global.anthropic.claude-sonnet-5,global.anthropic.claude-sonnet-4-6,meta.llama3-1-8b-instruct-v1:0 ``` -Note: If omitted, all known, supported model IDs will be included automatically. +If omitted, LibreChat includes its known supported models automatically. Claude 4 and newer defaults use Bedrock cross-region inference profile IDs because their bare `anthropic.` foundation-model IDs do not support on-demand Converse requests. LibreChat uses `global.` profiles where available and `us.` for Claude Opus 4.1. Use `BEDROCK_AWS_MODELS` to select a different profile available to your account. -- Claude Fable/Mythos-class models on Bedrock are inference-profile only. Use a profile ID such as `us.anthropic.claude-fable-5`, and enable Anthropic data sharing in the Bedrock console or Data Retention API before invoking them. +- Claude Fable/Mythos-class models on Bedrock are inference-profile only. Use a profile ID such as `global.anthropic.claude-fable-5`, and enable Anthropic data sharing in the Bedrock console or Data Retention API before invoking them. + +- Claude Opus 5 has a 1M-token context window and 128K-token maximum output. Adaptive thinking is enabled unless explicitly disabled. When thinking is disabled, LibreChat limits `xhigh` or `max` effort to `high` so Bedrock accepts the request. + +- Claude Sonnet 5 has a 1M-token context window and 128K-token maximum output. LibreChat applies adaptive thinking to foundation, cross-region inference-profile (for example, `us.anthropic.claude-sonnet-5`), and bare application inference-profile IDs. Turning thinking off sends an explicit disabled setting so that choice persists when a conversation is reloaded. - See all Bedrock model IDs here: - **[https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html#model-ids-arns](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html#model-ids-arns)** @@ -154,7 +158,8 @@ Bedrock supports uploading documents directly to the provider via the `Upload to **Limitations:** -- Maximum file size per document: **4.5 MB** +- The default maximum file size is **4.5 MB**. +- When `fileConfig` does not set a smaller limit, Claude 4+ PDFs and Amazon Nova PDFs or DOCX files can be up to **32 MB**. - File names are automatically sanitized to conform to Bedrock's naming requirements (alphanumeric, spaces, hyphens, parentheses, square brackets; max 200 characters) For more information on file upload options, see the [OCR for Documents](/docs/features/ocr#5-upload-files-to-provider-direct) documentation. diff --git a/content/docs/configuration/pre_configured_ai/google.mdx b/content/docs/configuration/pre_configured_ai/google.mdx index b878c2504..995ae0c70 100644 --- a/content/docs/configuration/pre_configured_ai/google.mdx +++ b/content/docs/configuration/pre_configured_ai/google.mdx @@ -3,7 +3,7 @@ title: 'Google' icon: Google --- -For the Google Endpoint, you can either use the **Generative Language API** (for Gemini models), or the **Vertex AI API** (for Gemini, PaLM2 & Codey models). +For the Google endpoint, you can use either the **Gemini API through Google AI Studio** or the **Vertex AI API**. The Generative Language API uses an API key, which you can get from **Google AI Studio**. @@ -42,21 +42,20 @@ GOOGLE_AUTH_HEADER=true Since fetching the models list isn't yet supported, you should set the models you want to use in the .env file. -For your convenience, these are the latest models as of 5/18/24 that can be used with the Generative Language API: +For example, the following current models can be configured for the Gemini API: ```bash filename=".env" -GOOGLE_MODELS=gemini-1.5-flash-latest,gemini-1.0-pro,gemini-1.0-pro-001,gemini-1.0-pro-latest,gemini-1.0-pro-vision-latest,gemini-1.5-pro-latest,gemini-pro,gemini-pro-vision +GOOGLE_MODELS=gemini-3.7-flash,gemini-3.6-flash,gemini-3.5-flash,gemini-3.5-flash-lite,gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash,gemini-2.0-flash-lite ``` -- A gemini-pro model or `gemini-pro-vision` are required in your list for attaching images. -- Using LibreChat, PaLM2 and Codey models can only be accessed through Vertex AI, not the Generative Language API. - - Only models that support the `generateContent` method can be used natively with LibreChat + the Gen AI API. -- Selecting `gemini-pro-vision` for messages with attachments is not necessary as it will be switched behind the scenes for you. -- Since `gemini-pro-vision` does not accept non-attachment messages, messages without attachments are automatically switched to use `gemini-pro` otherwise Google responds with an error. +- Gemini 3.7 Flash, Gemini 3.6 Flash, Gemini 3.5 Flash, and Gemini 3.5 Flash-Lite are supported through both Google AI Studio and Vertex AI. LibreChat assigns each a 1,048,576-token context window. +- LibreChat defaults Gemini 3.7 Flash, Gemini 3.6 Flash, and Gemini 3.5 Flash to `MEDIUM` thinking, and Gemini 3.5 Flash-Lite to `MINIMAL`. Gemini 3.7 Flash rejects `MINIMAL`, so LibreChat substitutes `LOW` when that level is requested; other supported explicit `thinkingLevel` values are preserved. +- For these models, LibreChat removes unsupported sampling and penalty parameters (`temperature`, `topP`, `topK`, `presencePenalty`, and `frequencyPenalty`), ignores the older numeric `thinkingBudget`, and uses `thinkingLevel` instead. +- Gemini 3.7 Flash does not support assistant prefill. LibreChat prevents edited assistant replies from being resubmitted as an unsupported trailing model-role turn. +- Built-in cost estimates use the Gemini 3.6/3.7 Flash introductory rates through December 31, 2026: $0.75 input, $3.75 output, and $0.075 cached input per million tokens. - With the Google endpoint, you cannot use both Vertex AI and Generative Language API at the same time. You must choose one or the other. -- Some PaLM/Codey models and `gemini-pro-vision` may fail when `maxOutputTokens` is set to a high value. If you encounter this issue, try reducing the value through the conversation parameters. @@ -170,10 +169,10 @@ GOOGLE_CLOUD_LOCATION=global Since fetching the models list isn't yet supported, you should set the models you want to use in the .env file. -For your convenience, these are the latest models as of 5/18/24 that can be used with the Generative Language API: +For Vertex AI, use the Vertex model IDs where they differ from the Gemini API: ```bash filename=".env" -GOOGLE_MODELS=gemini-1.5-flash-preview-0514,gemini-1.5-pro-preview-0514,gemini-1.0-pro-vision-001,gemini-1.0-pro-002,gemini-1.0-pro-001,gemini-pro-vision,gemini-1.0-pro +GOOGLE_MODELS=gemini-3.7-flash,gemini-3.6-flash,gemini-3.5-flash,gemini-3.5-flash-lite,gemini-3.1-pro-preview,gemini-3.1-pro-preview-customtools,gemini-3.1-flash-lite-preview,gemini-2.5-pro,gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.0-flash-001,gemini-2.0-flash-lite-001 ``` diff --git a/content/docs/configuration/pre_configured_ai/openai.mdx b/content/docs/configuration/pre_configured_ai/openai.mdx index d165f05fa..1488b6955 100644 --- a/content/docs/configuration/pre_configured_ai/openai.mdx +++ b/content/docs/configuration/pre_configured_ai/openai.mdx @@ -21,12 +21,14 @@ OPENAI_API_KEY=user_provided - When `OPENAI_API_KEY` is set to the actual API key value โ†’ as long as `OPENAI_MODELS` is left commented-out, it will do an API call to find out what models are available, which should include any new ones ```bash filename=".env" -OPENAI_MODELS=gpt-5,gpt-5-codex,gpt-5-mini,gpt-5-nano,o3-pro,o3,o4-mini,gpt-4.1,gpt-4.1-mini,gpt-4.1-nano,o3-mini,o1-pro,o1,gpt-4o,gpt-4o-mini +OPENAI_MODELS=gpt-5.6,gpt-5.6-terra,gpt-5.6-luna,gpt-5.5,gpt-5.5-pro,chat-latest,gpt-5.4,gpt-5.4-pro,gpt-5.4-mini,gpt-5.4-nano,gpt-5.3-codex,gpt-5.2,gpt-5,gpt-5-codex,gpt-5-mini,gpt-5-nano,o3-pro,o3,o4-mini,gpt-4.1,gpt-4.1-mini,gpt-4.1-nano,o3-mini,o1-pro,o1,gpt-4o,gpt-4o-mini ``` **Notes:** -- Internal OpenAI defaults include the current frontier catalog, including `gpt-5.5`, `gpt-5.5-pro`, `chat-latest`, `gpt-5.4`, `gpt-5.4-pro`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.3-codex`, and `gpt-5.2`. Deprecated legacy defaults are no longer included unless you add them explicitly with `OPENAI_MODELS`. +- Internal OpenAI defaults include `gpt-5.6`, `gpt-5.6-terra`, and `gpt-5.6-luna`, followed by the existing GPT-5 catalog. `gpt-5.6` is the Sol tier alias; LibreChat assigns all three GPT-5.6 tiers a 1,050,000-token context window and 128,000-token maximum output. Deprecated legacy defaults are no longer included unless you add them explicitly with `OPENAI_MODELS`. +- GPT-5.6 supports the Responses API-only `reasoning_mode` values `standard` and `pro`, plus `reasoning_context` values `auto`, `current_turn`, and `all_turns`. These can be configured in [model specs](/docs/configuration/librechat_yaml/object_structure/model_specs#reasoning_mode). +- For a GPT-5.6 model with a non-`none` `reasoning_effort`, LibreChat defaults the canonical OpenAI endpoint to the Responses API so function tools remain compatible. An explicit `useResponsesApi: false` keeps Chat Completions. Azure OpenAI, OpenRouter, and custom or reverse-proxy base URLs are not switched automatically. - Selecting a vision model for messages with attachments is not necessary as it will be switched behind the scenes for you. If you didn't outright select a vision model, it will only be used for the vision request and you should still see the non-vision model you had selected after the request is successful - OpenAI Vision models allow for messages without attachments - OpenAI endpoint supports all [Shared Endpoint Settings](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings) via the `librechat.yaml` configuration file, including `streamRate`, `headers`, `titleModel`, `titleMethod`, `titlePrompt`, `titlePromptTemplate`, and `titleEndpoint` diff --git a/content/docs/configuration/redis.mdx b/content/docs/configuration/redis.mdx index 9da6678ca..f3508c7cf 100644 --- a/content/docs/configuration/redis.mdx +++ b/content/docs/configuration/redis.mdx @@ -15,6 +15,9 @@ This guide covers how to configure Redis for caching and session storage in Libr - [Performance Tuning](#performance-tuning) - [Configuration Examples](#configuration-examples) - [Resumable Streams](#resumable-streams) +- [Generation Protocol Rollout](#generation-protocol-rollout) +- [Stream Delta Coalescing](#stream-delta-coalescing) +- [MCP Catalog Coordination](#mcp-catalog-coordination) ## Basic Setup @@ -323,6 +326,42 @@ REDIS_URI=redis://127.0.0.1:6379 # USE_REDIS_STREAMS=true # Enabled by default when USE_REDIS=true ``` +### Generation Protocol Rollout + +The v2 generation protocol adds the durable queue, interrupt, pause/resume, and recovery guarantees used by current Agent runs. Redis-backed deployments intentionally remain on protocol v1 when `GENERATION_PROTOCOL_VERSION` is unset so replicas running different LibreChat versions can coexist during a rolling upgrade. + +Use a two-stage rollout: + +1. Deploy the v2-capable LibreChat image to **every** replica with `GENERATION_PROTOCOL_VERSION` unset or set to `1`. +2. Wait for active generations owned by the previous image to finish or drain. +3. Set `GENERATION_PROTOCOL_VERSION=2` and roll out the same image again. + +```bash filename=".env" +USE_REDIS=true +USE_REDIS_STREAMS=true +GENERATION_PROTOCOL_VERSION=2 +``` + + + Do not enable protocol v2 until every replica supports it. After v2 generations begin, do not roll back to a pre-v2 LibreChat image until those generations have drained; older replicas cannot safely operate on their Redis state. + + +In-memory generation streams do not share state across replicas and use protocol v2 by default, so they do not require this cutover. + +### Stream Delta Coalescing + +Redis-backed streams can batch delta publications to reduce Redis scripts, round trips, and CPU at high token rates: + +```bash filename=".env" +STREAM_DELTA_COALESCE_MS=25 +``` + +The setting is off when unset or set to `0`, `25` milliseconds is recommended, and values above `1000` are capped. Batching can add up to one configured window of delivery latency. + + + Enable coalescing only after every LibreChat replica supports batch frames. Older subscribers drop coalesced frames. + + ### Key Benefits (for Horizontal Scaling) - **Cross-instance continuity**: Users can start a generation on one server and resume on another @@ -342,3 +381,9 @@ REDIS_URI=redis://node1:7001,redis://node2:7002,redis://node3:7003 ``` See [Resumable Streams](/docs/features/resumable_streams) for more details on this feature. + +## MCP Catalog Coordination + +When Redis is enabled, LibreChat coordinates application-level MCP tool catalogs across replicas. Startup publication, reconnect synchronization, and `notifications/tools/list_changed` updates use generation and revision markers so a stale replica cannot overwrite a newer catalog. + +Redis Cluster deployments use slot-safe catalog keys and update operations; no separate MCP Redis setting is required. See [MCP Server Management](/docs/features/mcp#mcp-server-management) for dynamic catalog and OAuth readiness behavior. diff --git a/content/docs/configuration/stt_tts.mdx b/content/docs/configuration/stt_tts.mdx index 402867da5..deca94586 100644 --- a/content/docs/configuration/stt_tts.mdx +++ b/content/docs/configuration/stt_tts.mdx @@ -32,6 +32,8 @@ These keys are then referenced in your `librechat.yaml` configuration using `${S The `speechTab` menu provides customizable options for conversation and advanced modes, as well as detailed settings for STT and TTS. This will set the default settings for users +Use `browser` for built-in browser speech or `external` for a server-side provider configured below. Older provider-specific defaults remain accepted for compatibility and are normalized to `external`; if the matching external service is unavailable, LibreChat falls back to `browser`. + example: ```yaml diff --git a/content/docs/configuration/token_usage.mdx b/content/docs/configuration/token_usage.mdx index 7092127a3..60b7a54d5 100644 --- a/content/docs/configuration/token_usage.mdx +++ b/content/docs/configuration/token_usage.mdx @@ -17,6 +17,7 @@ LibreChat shows a context gauge while a conversation is running. The gauge updat - Current prompt/context usage against the model's context window - A hover summary for quick token and cost details - A click-through breakdown for prompt, completion, cached token usage, branch totals, and conversation totals +- For authorized administrators, a direct Langfuse session link when the conversation has a sampled trace in the active in-app connection Usage breakdowns are persisted with messages and conversations. Reopened chats retain branch and total usage/cost details instead of relying only on the active streaming session. diff --git a/content/docs/features/access_control.mdx b/content/docs/features/access_control.mdx index 0fca8329e..80e151fa0 100644 --- a/content/docs/features/access_control.mdx +++ b/content/docs/features/access_control.mdx @@ -159,14 +159,17 @@ The canonical capabilities include: | `read:users` / `manage:users` | View / modify user accounts | | `read:groups` / `manage:groups` | View / modify groups | | `read:roles` / `manage:roles` | View / modify custom roles | -| `read:configs` / `manage:configs` | View / modify system configuration | +| `read:configs` / `manage:configs` | View / modify all system configuration | +| `read:configs:
` / `manage:configs:
` | View / modify one top-level configuration section | | `assign:configs:{user\|group\|role}` | Assign config-override profiles to principals | | `read:usage` | View platform usage and telemetry | | `read:agents` / `manage:agents` | View / moderate every agent on the instance | | `read:prompts` / `manage:prompts` | View / moderate every prompt | | `manage:mcpservers` | Manage MCP servers globally | -Manage capabilities imply their corresponding read capability (e.g. holding `manage:users` automatically grants `read:users`). A `SystemRoles.ADMIN` user implicitly holds all capabilities; grants let you **delegate** a subset of admin powers to non-admin principals without making them full admins. +Manage capabilities imply their corresponding read capability (e.g. holding `manage:users` automatically grants `read:users`). This also applies to configuration sections: `manage:configs:endpoints` satisfies `read:configs:endpoints`. Users with only section-scoped config access receive admin configuration responses filtered to the sections they can read; users with no config-read grant receive `403`. + +A `SystemRoles.ADMIN` user implicitly holds all capabilities; grants let you **delegate** a subset of admin powers to non-admin principals without making them full admins. Access to the admin UI itself still requires `access:admin`. System grants are issued and revoked via the admin panel. @@ -185,6 +188,21 @@ A group is a named collection of users. LibreChat supports two sources: Groups can appear in any ACL, in `peoplePicker` search, and as a principal target for config overrides or system grants. A single resource shared with a 500-person group is one ACL entry (not 500), and membership changes in Entra propagate automatically on the next login. +### ACL Principal Cache Tuning + +LibreChat caches the group IDs used to resolve a user's ACL principals for five minutes by default. The cache is scoped by tenant and member identity, and group membership changes invalidate affected entries. It does not cache the user's role or the lookup of `idOnTheSource`, so those values continue to be resolved from the current request user or database. + +```bash filename=".env" +# Group-membership cache lifetime; 0 disables the cache +USER_PRINCIPALS_CACHE_TTL_MS=300000 + +# Redis-backed deployments only: deduplicate cold cache builds across replicas +USER_PRINCIPALS_LOCK_TTL_MS=5000 +USER_PRINCIPALS_LOCK_WAIT_MS=5000 +``` + +When the principal cache is Redis-backed, the lock settings prevent several replicas from rebuilding the same cold entry at once. Set `USER_PRINCIPALS_LOCK_TTL_MS=0` to disable only build locking; shared cache storage and cross-process invalidation remain active. Cache and lock failures fall back to the database and do not block permission checks. + ### Roles Any system or custom role can be used as a principal. Sharing an agent with a role (e.g. `SupportEngineers`) gives every user currently holding that role access, without needing to enumerate individuals. Roles can be hidden from the people picker via [`interface.peoplePicker.roles`](/docs/configuration/librechat_yaml/object_structure/interface#peoplepicker) for environments where role-based sharing is an admin-only concern. diff --git a/content/docs/features/admin_panel.mdx b/content/docs/features/admin_panel.mdx index 9784d068d..18dd98707 100644 --- a/content/docs/features/admin_panel.mdx +++ b/content/docs/features/admin_panel.mdx @@ -146,14 +146,14 @@ bun dev # http://localhost:3000 | `VITE_API_BASE_URL` | **Yes** in Docker | `http://localhost:3080` (local dev only) | Browser-facing URL of the LibreChat API server, used for OAuth redirects. | | `API_SERVER_URL` | No | Falls back to `VITE_API_BASE_URL` | Server-side URL for LibreChat API calls. Useful when the admin-panel server reaches LibreChat on a different URL than the browser (e.g. internal Kubernetes service vs. public hostname). | | `PORT` | No | `3000` | Port the admin panel listens on. | -| `ADMIN_PANEL_SESSION_SECRET` | **Yes** in production | Falls back to `CREDS_KEY` in bundled LibreChat Docker stacks | LibreChat-side variable mapped to the admin panel's `SESSION_SECRET` for the bundled admin-panel service. Generate a unique value of at least 32 characters for production. | +| `ADMIN_PANEL_SESSION_SECRET` | **Yes** | _unset_ | LibreChat-side variable mapped to the admin panel's `SESSION_SECRET` for the bundled admin-panel service. Generate a unique value of at least 32 characters before starting the panel. | | `ADMIN_PANEL_PORT` | No | `3000` | Host port exposed by the bundled admin-panel service in the default `docker-compose.yml`. | | `ADMIN_SSO_ONLY` | No | `false` | Hide the email/password form, forcing SSO-only login. | | `ADMIN_SESSION_IDLE_TIMEOUT_MS` | No | `1800000` (30 min) | Session idle timeout in milliseconds. | | `SESSION_COOKIE_SECURE` | No | `true` in production | Whether the session cookie requires HTTPS. | | `ADMIN_PANEL_METRICS_SECRET` | No | _unset_ | Bearer token required to scrape the `/metrics` Prometheus endpoint. The endpoint returns `401` when unset or mismatched. | -In LibreChat's bundled Docker stacks, the admin panel runs as an `admin-panel` service. The default `docker-compose.yml` exposes it on `ADMIN_PANEL_PORT`; `deploy-compose.yml` routes it through nginx at `http://admin.localhost` and sets `ADMIN_PANEL_URL` for the API service. +In LibreChat's bundled Docker stacks, the admin panel runs as an `admin-panel` service. The default `docker-compose.yml` exposes it on `ADMIN_PANEL_PORT`; `deploy-compose.yml` routes it through nginx at `http://admin.localhost` and sets `ADMIN_PANEL_URL` for the API service. The panel refuses to start until `ADMIN_PANEL_SESSION_SECRET` is configured. ### LibreChat Redirect URL @@ -163,6 +163,8 @@ When the admin panel is hosted on a separate URL from LibreChat, set `ADMIN_PANE ADMIN_PANEL_URL=https://admin.example.com/admin ``` +When set, LibreChat also shows an **Admin Panel** link to administrators under **Settings -> General**. Non-admin users do not see the link. + For Helm deployments, set `librechat.adminPanelUrl` in your values file. The chart renders it as `ADMIN_PANEL_URL` for LibreChat's admin OAuth flow: ```yaml filename="values.yaml" @@ -198,6 +200,8 @@ Admin access is verified server-side by LibreChat for every request. The account Sessions are cookie-based, encrypted with `SESSION_SECRET`, and idle-expire per `ADMIN_SESSION_IDLE_TIMEOUT_MS`. +Google admin SSO requests offline access and consent so the panel can refresh an expired LibreChat admin token without forcing an immediate new login. Configure both `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, and register `${DOMAIN_SERVER}/api/admin/oauth/google/callback` with Google. Each refresh rechecks the account's provider identity, ban state, allowed email domain, tenant, and current admin access; losing access ends the admin session. + ## Configuration Management The panel renders the LibreChat config as a dynamic form driven by the config schema. This has two useful properties: @@ -211,6 +215,18 @@ This is the surface behind LibreChat's [DB-backed per-principal configuration ov - Let a "FinanceAdmins" role manage MCP servers while regular users can only use them - Scope stricter `interface` permissions to external-contractor groups +### Section-Scoped Delegation + +Configuration grants can be broad (`read:configs`, `manage:configs`) or limited to one top-level section (`read:configs:
`, `manage:configs:
`). A section-scoped reader receives a filtered configuration response containing only authorized sections instead of being denied the entire request. Section-level manage grants imply read access to the same section; broad manage access implies broad read access. + +Examples include `read:configs:interface`, `manage:configs:endpoints`, and `manage:configs:langfuse`. Delegated users still need `access:admin` to enter the admin surface. Every create, patch, tombstone, or delete mutation of the base `__base__` profile requires broad `manage:configs`; section-scoped management applies to role, group, and user overrides. + +### Stored Secrets + +When registered secret fields are written through the admin configuration API, LibreChat encrypts literal values at rest and returns only server-generated masked previews. This currently covers Langfuse, OCR, speech, web-search, Assistants, Azure Assistants, and each `endpoints.custom[].apiKey`. Omitting a secret during a later edit preserves the stored value. + +Supported environment references remain readable references for fields that allow them. Custom endpoint API keys also preserve `${ENV_VAR}` and `user_provided` values instead of encrypting them. Secret handling is registry-based: arbitrary values in generic maps such as custom headers or MCP configuration are not automatically encrypted, so continue to use environment references or the feature's dedicated credential mechanism there. + ## Related - [Access Control](/docs/features/access_control): the permission model the admin panel is built on diff --git a/content/docs/features/agent_plugins.mdx b/content/docs/features/agent_plugins.mdx new file mode 100644 index 000000000..0820e3d06 --- /dev/null +++ b/content/docs/features/agent_plugins.mdx @@ -0,0 +1,163 @@ +--- +title: Agent Plugins +icon: Plug +description: Experimentally bundle deployment Skills, MCP servers, and command hooks into startup-loaded packages. +--- + +Agent Plugins let an operator package related [Skills](/docs/features/skills), [MCP servers](/docs/features/mcp), and optional command hooks together on the LibreChat filesystem. LibreChat implements the Agent Plugins `1.0.0` package format and loads each immediate child directory as one plugin at startup. + + + Agent Plugins are experimental. The package format, supported components, configuration, and runtime behavior may change during the experimentation phase. Test plugins before using them in a production deployment. + + +## Configure the Directories + +```bash filename=".env" +# Defaults to ./plugin relative to the LibreChat project root +DEPLOYMENT_PLUGINS_DIR=./plugin + +# Persistent data allocated separately for each plugin manifest name +DEPLOYMENT_PLUGIN_DATA_DIR=./data/plugins + +# Optional and disabled by default; see Command Hooks below +DEPLOYMENT_PLUGIN_HOOKS=true +``` + +Relative paths are resolved from the LibreChat project root. If the default `./plugin` directory does not exist, startup continues with no plugins. If `DEPLOYMENT_PLUGINS_DIR` is set explicitly but cannot be read, startup fails so a deployment mistake is not silently ignored. + +Restart LibreChat after adding, removing, or changing a plugin. + +## Package Layout + +Each immediate child of `DEPLOYMENT_PLUGINS_DIR` is one plugin package: + +```text +plugin/ + analytics-tools/ + plugin.json + skills/ + analyze-events/ + SKILL.md + scripts/ + analyze.py + mcp.json + ai.librechat/ + hooks/ + hooks.json + scripts/ + guard.sh +``` + +`plugin.json` is required. `skills/`, `mcp.json`, and `ai.librechat/hooks/hooks.json` are optional and fail independently, so one invalid component does not prevent another valid component in the same plugin from loading. An invalid or missing manifest rejects the complete plugin. Diagnostics are written to the LibreChat startup logs. + +## Manifest + +The manifest must use the exact Agent Plugins `1.0.0` schema URL: + +```json filename="plugin.json" +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "analytics-tools", + "version": "1.0.0", + "description": "Skills and tools for analyzing event data" +} +``` + +The `name` is also used for the plugin's persistent data directory. It must be 1-64 characters, start and end with a lowercase letter or number, use only lowercase letters, numbers, hyphens, and periods, and cannot contain consecutive `--` or `..` sequences. Plugin names must be unique within the deployment. + +## Bundled Skills + +Put each Skill in an immediate child directory under `skills/`, with `SKILL.md` at that child's root. LibreChat loads valid entries as read-only deployment Skills and applies the normal Skills capability and access rules. + +The standalone [`DEPLOYMENT_SKILLS_DIR`](/docs/features/skills#deployment-skills) takes precedence over a plugin Skill with the same name. Within the plugin directory, the first package to claim a Skill name wins and later conflicts are skipped with a warning. + +## Bundled MCP Servers + +Define optional MCP servers in `mcp.json` with the exact `1.0.0` schema URL: + +```json filename="mcp.json" +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "analytics": { + "type": "stdio", + "command": "node", + "args": ["${PLUGIN_ROOT}/server.js"], + "cwd": "${PLUGIN_ROOT}", + "env": { + "PLUGIN_CACHE": "${PLUGIN_DATA}/cache" + } + } + } +} +``` + +Supported transports are `stdio`, `streamable-http`, and `sse`. Remote HTTP transports must use HTTPS except for loopback destinations. Server names must survive LibreChat's MCP tool-name normalization unchanged and cannot use reserved JavaScript object names. + +For `stdio` servers, `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` are expanded once in `args`, `env`, and `cwd`; both values are also added to the launched process environment. Plugin MCP configuration does not expand arbitrary variables from LibreChat's host environment. A value such as `${OPENAI_API_KEY}` remains literal through registry storage and runtime initialization. Keep credentials outside plugin files and provide them through a purpose-built authenticated service or another deployment-controlled mechanism. + +An MCP server declared in `librechat.yaml` takes precedence over a plugin server with the same name. Duplicate plugin server names are skipped and logged. + +## Persistent Plugin Data + +LibreChat creates one directory at `/` and exposes it to `stdio` components as `${PLUGIN_DATA}`. Use it for plugin-owned persistent state. Do not write persistent state into `${PLUGIN_ROOT}`, which should be treated as package content. + +## Command Hooks + +Agent Plugins can run `command` hook handlers at Agent lifecycle boundaries. Hook execution is disabled by default. Enable it explicitly and restart LibreChat: + +```bash filename=".env" +DEPLOYMENT_PLUGIN_HOOKS=true +``` + +When the variable is false or unset, LibreChat ignores hook documents and logs a startup warning; the plugin's independently valid Skills and MCP servers still load. + + + A command hook runs an operator-installed child process on the LibreChat API host. The restricted + environment reduces accidental exposure but is not a sandbox. Enable hooks only for plugin + packages you trust at the same level as LibreChat code and `toolApproval` hook modules. + + +Declare hooks at `ai.librechat/hooks/hooks.json`: + +```json filename="ai.librechat/hooks/hooks.json" +{ + "description": "Reject writes outside the workspace", + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/guard.sh", + "timeout": 30, + "allowedEnvVars": ["WORKSPACE_POLICY"] + } + ] + } + ] + } +} +``` + +### Execution Contract + +- LibreChat starts the command from the plugin root and sends a Claude-compatible event payload as JSON on standard input. +- `${PLUGIN_ROOT}`, `${PLUGIN_DATA}`, and `${CLAUDE_PLUGIN_ROOT}` are expanded once in `command` and `args` and are also available to the child process. +- The child environment contains only `PATH`, `HOME`, `LANG`, `LC_ALL`, and `TZ` when present, the three plugin path variables, and names explicitly listed in `allowedEnvVars`. +- Exit code `0` succeeds. JSON written to standard output can return event-appropriate decisions and bounded context; plain output is treated as additional context only for `SessionStart` and `UserPromptSubmit`. +- Exit code `2` blocks the applicable action or continuation and uses standard error as the reason. Other nonzero exits are logged and otherwise ignored. +- LibreChat terminates the process when the hook is aborted or times out. On POSIX hosts, commands run through Bash. Windows plugins must provide `commandWindows` or select PowerShell. + +LibreChat translates the common Claude tool names `Bash`, `Write`, `Edit`, `Read`, and `WebSearch` and their file argument names to the corresponding LibreChat tools. A matcher written with LibreChat's native tool name keeps the native payload shape. + +Supported source events are `RunStart`, `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `Stop`, `StopFailure`, `PreCompact`, and `PostCompact`. Unsupported events or declarations are skipped and reported in startup diagnostics. Only `command` handlers execute in this release; `prompt`, `http`, `mcp_tool`, and `agent` handlers remain unsupported. + +`SessionStart` and handlers with `once: true` are deduplicated per conversation by a bounded process-local store. In a multi-replica deployment, the same once-only handler can run once on each process. An `ask` decision requires LibreChat's resumable human-approval flow; when that flow is unavailable, LibreChat tightens the decision to `deny` instead of leaving the run paused without a resume path. + +## Related + +- [Skills](/docs/features/skills) +- [Model Context Protocol](/docs/features/mcp) +- [Agents](/docs/features/agents) diff --git a/content/docs/features/agents.mdx b/content/docs/features/agents.mdx index b1dc1671b..cd205d2f7 100644 --- a/content/docs/features/agents.mdx +++ b/content/docs/features/agents.mdx @@ -24,12 +24,24 @@ The creation form includes: - **Instructions**: System instructions that define your agent's behavior - **Model**: Select from available providers and models +The **Tools** and **Skills** controls open searchable libraries for built-in capabilities, tools, MCP servers, Actions, and Skills. Select an item to configure it, then save the agent. + **Existing agents can be selected from the top dropdown of the Side Panel.** - **Also by mention with "@" in the chat input.** ![Agents - Mention](/images/agents/mention.png) +### Tool Library + +The Agent Builder keeps enabled items in separate **Tools** and **Skills** sections. Open **Add tools** to search the complete catalog or filter it by **Official**, **Tools**, **MCP**, or **Actions**. **Made by you** collects MCP servers and Actions you created, while **Favorites** keeps starred items available across agents. Each user can save up to 100 tool-library favorites. + +Select an item to configure it without leaving the builder. The **Create new** menu appears only when the user has permission to create MCP servers or Actions. Removing a file-backed capability such as File Search, File Context, or Code Interpreter opens its file manager when attached files still need to be reviewed. + +Skills use their own picker and can be selected individually or enabled as the complete accessible catalog. See [Skills](/docs/features/skills#agent-scope). + +Operators can also use experimental [Agent Plugins](/docs/features/agent_plugins) to bundle deployment Skills and MCP servers into startup-loaded packages. + ### Model Configuration The model parameters interface allows fine-tuning of your agent's responses: @@ -39,6 +51,10 @@ The model parameters interface allows fine-tuning of your agent's responses: - Max output tokens - Additional provider-specific settings +### Version History + +Users with edit access can open **Version History** from the Agent Builder to inspect saved configurations in a timeline. Each entry shows when it was saved and summarizes its tools and capabilities. Restoring an earlier entry requires confirmation and replaces the current agent configuration with that saved state. Saving always applies the Agent's current changes, even when the resulting configuration matches the newest history entry and LibreChat does not add a duplicate entry. + ## Agent Capabilities > **Note:** All capabilities can be toggled via the `librechat.yaml` configuration file. See [docs/configuration/librechat_yaml/object_structure/agents#capabilities](/docs/configuration/librechat_yaml/object_structure/agents#capabilities) for more information. @@ -55,6 +71,18 @@ When enabled, the Code Interpreter capability allows your agent to: - [More info about the Code Interpreter API](/docs/features/code_interpreter) - **Powered by the open-source [code-interpreter](https://github.com/ClickHouse/code-interpreter) service (self-hosted)** +When every required Code Interpreter file from a conversation fails to restore into the current sandbox, LibreChat stops the Agent before invoking the model and asks the user to reattach the files. This prevents the run from continuing with stale or inaccessible file references. + +#### Stateful Code Sessions + +Stateful code sessions let an agent reuse one sandbox workspace per conversation. Files, installed packages, and working state usually carry over between code executions, which is useful for iterative analysis and multi-step file work. + + + Stateful Code Sessions are in an early experimentation phase. Their behavior, configuration, persistence characteristics, and underlying integration may change substantially. Do not treat the current implementation as a stable production contract. + + +This feature is opt-in. An administrator must add `stateful_code_sessions` to the [agent capabilities](/docs/configuration/librechat_yaml/object_structure/agents#capabilities), Code Interpreter must be enabled on the agent, and **Stateful code sessions** must be turned on under the agent's Advanced settings. The workspace may reset at any time. Save important outputs under `/mnt/data`, and do not otherwise rely on session state as durable storage. + ### File Search The File Search capability enables: @@ -91,8 +119,8 @@ For more information, see documentation on [MCP](/docs/features/mcp). 1. Configure MCP servers in your `librechat.yaml` file 2. Restart LibreChat to initialize the connections 3. Create or edit an agent -4. Click the "Add Tools" button in the Agent Builder panel to open the Tools Dialog shown below -5. Select the MCP server(s) you want to add - each server appears as a single entry +4. Open **Add tools** in the Agent Builder and select **MCP** +5. Select the MCP server(s) you want to add; each server appears as a single entry 6. Save your changes to the agent In this example, we've added the **[Spotify MCP server](https://github.com/LibreChat-AI/spotify-mcp)** to an agent. @@ -108,6 +136,10 @@ Once an MCP server is added to an agent, you can fine-tune which specific tools - For example, the Spotify MCP server provides ~20 tools (search, playback control, playlist management, etc.) - This granular control lets you limit agents to only the tools they need +Request-scoped servers that use `{{LIBRECHAT_BODY_*}}` cannot enumerate tools until a chat run supplies those values. Agent Builder therefore shows one runtime-tools selection for the complete server instead of per-tool toggles; clearing that selection detaches the server. After OAuth, LibreChat keeps the authorization and waits until the first eligible run to connect. + +If an Agent explicitly selects MCP tools but none can be resolved when a run starts, LibreChat stops the run with connection and access guidance instead of silently continuing without them. Reconnect or authenticate the server, verify tool access, and retry the run. + ![Agents - MCP Tools](/images/agents/mcp_agent_tools.png) Learn More: @@ -135,6 +167,22 @@ This is especially useful when an agent has access to many MCP servers with doze **Note:** The `deferred_tools` capability is enabled by default. It can be toggled via the [`librechat.yaml` agents configuration](/docs/configuration/librechat_yaml/object_structure/agents#capabilities). +### Activity Groups + +Activity groups collapse each contiguous block of Agent reasoning and tool calls under a generated one-line header, making long runs easier to scan. Administrators enable them with `activityLabel` and can use a faster model, another configured endpoint, a custom prompt, and per-run limits. Header generation is a separate model call whose tokens and cost are recorded. See [Agent Activity Groups](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings#agent-activity-groups). + +Administrators can independently enable `activityPhaseLabel` to wrap two or more logical activities in a collapsed parent summary before the final answer. This gives long runs a higher-level outline while preserving each child activity. Phase summaries use their own model, endpoint, prompt, and per-run cap, with fallback to the activity-label and run settings. + +Short progress text remains inside its parent phase. When the Agent begins a substantial answer, LibreChat closes the phase before that text so the user-facing result stays outside the collapsed summary. One run can create multiple parent phases when later reasoning or tools begin another logical activity block. Persisted phase boundaries are rebased when malformed or omitted content parts are compacted, so the grouping remains aligned after reload. + +### Tool Intent Labels + +Tool intent labels replace generic live tool statuses with a short description written by the model for that specific call. Administrators must add the opt-in `tool_intents` [agent capability](/docs/configuration/librechat_yaml/object_structure/agents#capabilities). Native tools use labels automatically; in the Agent Builder, expand an MCP server and turn on **Intent label** for individual tools or the full server. + +For model specs, [`describeIntent`](/docs/configuration/librechat_yaml/object_structure/model_specs#describeintent) can enable every eligible tool or select resolved tool IDs. Intent fields add to the tool schema sent to the model, so selective enablement can reduce schema-token overhead. + +Intent labels do not apply to programmatic-only MCP tools because calls made inside sandbox code do not render individual tool cards. + ### Programmatic Tool Calling Programmatic Tool Calling (PTC) lets agents execute selected MCP tools from inside the [Code Interpreter](/docs/features/code_interpreter) sandbox instead of calling each tool directly from the model. The model receives a Code Interpreter-backed orchestration tool, writes sandboxed code that calls generated tool functions, and can use loops, conditionals, retries, and result processing before returning an answer. @@ -149,12 +197,43 @@ This is useful for multi-step tool workflows such as querying several resources, **Note:** `programmatic_tools` is opt-in and is not included in the default agents capability list. PTC also requires a Code Interpreter deployment with the Tool Call Server component. Only tools registered for the agent can be called from the sandbox; unregistered tool calls are rejected. +### Background Tool Calls + +Background tool calls let an agent start a long-running eligible MCP or Code Interpreter tool, keep working, and poll for the result later. The initial call returns immediately with a task reference; the agent retrieves status and results through `check_background_task`. + +To use this feature, an administrator must add the opt-in `run_in_background` [agent capability](/docs/configuration/librechat_yaml/object_structure/agents#capabilities). Then configure the eligible tools in the Agent Builder: + +- **Code Interpreter:** Enable Code Interpreter on the agent. Code execution and shell commands become background-eligible by default; turn off **Background execution** in its tool settings to opt out. +- **MCP:** Open an MCP server and mark individual tools, or the full server, as **Background**. + +These settings allow background execution but do not force it. The model decides per call whether to run an eligible tool in the background. + +In LibreChat chat, when background code finishes, its stdout and generated files appear on the original code call rather than the later poll. Generated files are also persisted for subsequent turns. + +Background task state is currently process-local. Results can be collected in a later turn on the same server process, but they do not survive a restart and are not shared across replicas. + +### Ask User and Tool Approval + +The **Ask User** tool lets an agent pause a run to request missing information, present choices, or confirm how to proceed. One call can group up to four related questions in a single form. Each question accepts a free-form answer or the agent's single- or multi-select choices; the user answers every question and submits once, or skips the form. While the model prepares the call, LibreChat streams the questions into a progress card; the interactive form replaces it when ready. After submission, the same run resumes with the answers. Add **Ask User** from the Tools marketplace; administrators can remove the default `ask_user_question` capability to hide it. + +Submitted answers are persisted with the resume action, so stopping while the resumed run initializes does not discard accepted answers. + +Each question accepts an optional heading up to 80 characters, question text up to 2,000 characters, optional supporting context up to 4,000 characters, and up to 12 choices. Choice labels are limited to 280 characters, choice values to 500 characters, and each submitted answer to 16,000 characters. + +Administrators can also require review before matching tool calls run. Depending on the tool, users can approve, reject, edit arguments, or respond directly. Paused runs are checkpointed so they can resume after the decision, including on another replica when the default MongoDB checkpointer is used. Tool approval is disabled by default; see [`toolApproval` and `checkpointer`](/docs/configuration/librechat_yaml/object_structure/agents#toolapproval). + ### Skills Skills let agents load reusable instructions from `SKILL.md` definitions. They can be selected manually from chat with `$`, automatically discovered by the model through the skill catalog, or always applied on every turn. For authoring, invocation, and access control details, see [Skills](/docs/features/skills). +### Memory + +The **Memory** tool lets an agent save, update, or delete structured user memories when the user explicitly asks it to remember or forget something. Memory must be configured for the deployment, allowed by the user's role and personalization settings, and enabled on the agent. + +By default, an agent uses the user's shared personal memory pool. Turn on **Keep memories separate for this agent** to give it a private per-user, per-agent partition. The isolated agent will not see existing shared memories or memories created by other isolated agents. Users can filter the Memory panel by personal or agent-specific memories. See [User Memory](/docs/features/memory#agent-memory). + ### Artifacts The Artifacts capability enables your agent to generate and display interactive content: @@ -164,14 +243,15 @@ The Artifacts capability enables your agent to generate and display interactive - Configure artifact-specific instructions at the agent level - [More info about Artifacts](/docs/features/artifacts) -When enabled, additional instructions specific to the use of artifacts are added by default. Options include: +When enabled, choose one of three instruction modes: -- **Enable shadcn/ui instructions**: Adds instructions for using shadcn/ui components (a collection of re-usable components built using Radix UI and Tailwind CSS) -- **Custom Prompt Mode**: When enabled, the default artifacts system prompt will not be included, allowing you to provide your own custom instructions +- **Normal**: Adds the standard artifact instructions for React, HTML, SVG, Markdown, and Mermaid. +- **shadcn/ui**: Adds the standard instructions plus guidance for building interfaces with the shadcn/ui component library. +- **Custom**: Keeps artifact rendering enabled but injects no built-in artifact instructions, giving the agent's own instructions full control. Configuring artifacts at the agent level is the preferred approach, as it allows for more granular control compared to the legacy app-wide configuration. -If you enable Custom Prompt Mode, you should include at minimum the basic artifact format in your instructions. +If you select **Custom**, include at minimum the basic artifact format in your instructions. Here's a simple example of the minimum instructions needed: @@ -198,10 +278,10 @@ For the type attribute, use one of: Agents can also be enhanced with various built-in tools: -- **[OpenAI Image Tools](/docs/features/image_gen#1--openai-image-tools-recommended)**: Image generation & editing using **[GPT-Image-1](https://platform.openai.com/docs/models/gpt-image-1)** +- **[OpenAI Image Tools](/docs/features/image_gen#openai-image-tools)**: Image generation & editing using **[GPT-Image-1](https://platform.openai.com/docs/models/gpt-image-1)** - **[Gemini Image Tools](/docs/configuration/tools/gemini_image_gen)**: Image generation and image-context editing using Gemini image models -- **[DALL-E-3](/docs/features/image_gen#3--dalle-legacy)**: Image generation from text descriptions -- **[Stable Diffusion](/docs/features/image_gen#4--stable-diffusion-local)** / **[Flux](/docs/features/image_gen#5--flux)**: Text-to-image generation +- **[DALL-E-3](/docs/features/image_gen#dalle-legacy)**: Image generation from text descriptions +- **[Stable Diffusion](/docs/features/image_gen#stable-diffusion-local)** / **[Flux](/docs/features/image_gen#flux)**: Text-to-image generation - **[Wolfram](/docs/configuration/tools/wolfram)**: Computational and mathematical capabilities - **[OpenWeather](/docs/configuration/tools/openweather)**: Weather data retrieval - **[Google Search](/docs/configuration/tools/google_search)**: Access to web search functionality @@ -242,6 +322,12 @@ With the Actions capability, you can dynamically create tools from [OpenAPI spec If using an OpenAI model supporting it, this will automatically generate function calls with 'strict' mode enabled. - Strict mode supports only a partial subset of json. Read https://platform.openai.com/docs/guides/structured-outputs for details. +### Handoffs + +Handoffs let a primary agent transfer a conversation to a specialist agent with the relevant context. In **Advanced settings**, open the orchestration section and add up to 10 handoff agents. Each configured handoff creates a transfer tool that the model can choose dynamically when the specialist's expertise is needed. + +For each handoff, you can add a description that helps the model choose the right specialist. You can also provide passthrough instructions describing what content the primary agent should generate for the specialist and optionally rename the content parameter from its default, `instructions`. Handoffs are always available in the Agent Builder; unlike Agent Chain and Subagents, they do not require an endpoint capability to be enabled. + ### Agent Chain The Agent Chain capability enables a Mixture-of-Agents (MoA) approach, allowing you to create a sequence of agents that work together: @@ -278,6 +364,8 @@ This setting allows you to limit the number of steps an agent can take in a "run If left unconfigured, the default is 25 steps, but you can adjust this to suit your needs. For admins, you can set a global default as well as a global maximum in the [`librechat.yaml`](/docs/configuration/librechat_yaml/object_structure/agents#recursionlimit) file. +Administrators can also bound streamed tool-call arguments and model delta events with [Agent stream circuit breakers](/docs/configuration/librechat_yaml/object_structure/agents#stream-circuit-breakers). + A "step" refers to either an AI API request or a round of tool usage (1 or many tools, depending on how many tool calls the LLM provides from a single request). A single, non-tool response is 1 step. A singular round of tool usage is usually 3 steps: @@ -351,6 +439,8 @@ The original author and administrators always retain full control regardless of 3. Search for users, groups, or roles in the people picker and assign each a role 4. Optionally toggle **Public** to make the agent visible to everyone on the instance (requires the `SHARE_PUBLIC` feature permission) +Agent cards and landing views show the configured support contact. When none is set, LibreChat can fall back to the first resolvable owner's display name, but does not expose the owner's email address unless it was configured explicitly as the support contact. + For full details on principals, permission bits, and how ACLs compose with role-based feature permissions, see [Access Control](/docs/features/access_control). ### Administrator Controls @@ -384,6 +474,23 @@ Individual users can: - Grant each recipient a different access level (Viewer / Editor / Owner) - Re-share or revoke access at any time from the share dialog +## Steering and Queued Messages + +While an Agent is responding, you can send another message in either of two ways: + +- **Steer** inserts the message into the current run at its next tool or agent step, so the agent can adjust its work before finishing. +- **Queue** holds the message and sends it as a normal follow-up turn after the current response completes. + +**Interrupt & steer** stops generation at the next provider-safe boundary, keeps the partial response, inserts the message, and resumes the same assistant response. Use the dedicated composer control, choose it from the send-button menu, or press `Command/Ctrl + Shift + .`. The action falls back to ordinary steering when the deployment cannot interrupt the active provider stream. + +Under **Settings โ†’ Chat**, **While generating, Enter will** chooses the default action. The send-button menu can override that choice for an individual message, and **Steering interrupts generation** controls whether ordinary steering also requests an interrupt. + +Pending steers appear above the composer until the server inserts them into the run. Once acknowledged, their menu can reclaim the message for editing, convert it into a queued follow-up, or cancel it and restore its text and attachments to the composer. LibreChat avoids overwriting a newer draft; if the composer is no longer available, it preserves the reclaimed message in the queue instead. A failed steer remains available to retry, edit, queue, or remove. + +Queued follow-ups can be sent immediately, converted into a steer while the run is still active, escalated to **Interrupt & steer now**, edited, or removed. In-flight steers offer the same escalation when they are still waiting for a tool boundary. Removing a queued message restores it to an empty composer when possible. One active run accepts up to 10 pending steers; each steer can include up to 10 files and is limited by [`STEER_MAX_LENGTH`](/docs/configuration/dotenv#agent-conversation-controls). + +Redis-backed multi-replica deployments must complete the [generation protocol v2 rollout](/docs/configuration/redis#generation-protocol-rollout) before relying on interrupt and recovery behavior across replicas. + ### Notes - Instructions, model parameters, attached files, and tools are only exposed to the user if they have editing permissions diff --git a/content/docs/features/artifacts.mdx b/content/docs/features/artifacts.mdx index e3d3b059f..43fa17d81 100644 --- a/content/docs/features/artifacts.mdx +++ b/content/docs/features/artifacts.mdx @@ -1,30 +1,43 @@ --- title: Artifacts - Generative UI icon: Palette -description: Discover LibreChat's revolutionary Artifacts feature for instant creation of React components, HTML code, and Mermaid diagrams. +description: Configure agents to render interactive React, HTML, SVG, Markdown, and Mermaid artifacts. --- -- **Generative UI:** Create React components, HTML code, and Mermaid diagrams -- **Flexible Integration:** Use any model you have set up -- **Iterative Design:** Rapidly improve and refine generated outputs -- **Agent Integration:** Configure artifacts at the agent level (recommended approach) +Artifacts let LibreChat Agents render generated React components, HTML, SVG, Markdown, and Mermaid content in a dedicated interactive view. Users can continue the conversation to revise the result while keeping the generated content separate from the chat response. -> **Note:** The preferred way to use artifacts is now through the [Agents feature](/docs/features/agents#artifacts), which allows for more granular control by enabling/disabling artifacts at the agent level rather than app-wide. +## Enable Artifacts for an Agent + +1. Create or edit an [Agent](/docs/features/agents). +2. Open **Add tools** and select **Artifacts**. +3. Choose an artifact instruction mode. +4. Save the agent. + +The available modes are: + +- **Normal**: Injects LibreChat's standard instructions for React, HTML, SVG, Markdown, and Mermaid artifacts. +- **shadcn/ui**: Adds shadcn/ui component-library guidance for more polished generated interfaces. +- **Custom**: Keeps artifact rendering enabled but injects no built-in instructions. Put the complete artifact behavior you want in the agent's instructions. + +Agent-level configuration is preferred because each agent can use the mode and instructions appropriate to its purpose. The administrator can hide Artifacts by removing the `artifacts` [agent capability](/docs/configuration/librechat_yaml/object_structure/agents#capabilities).
-## Key Features of LibreChat's Code Artifacts: +## What Artifacts Support + +- Interactive React components and HTML pages +- SVG images and Mermaid diagrams +- Rendered Markdown documents +- Iterative updates through follow-up messages +- Any model available to the configured agent -- Instant prototyping of websites and UIs with generative AI -- Effortless creation of dynamic, responsive layouts -- Interactive learning environment for React and HTML -- Complex idea visualization using Mermaid diagrams -- AI-powered intuitive, user-centric design iterations -- Free and open-source alternative to paid AI tools +## Preview and Export -Experience the future of UI/UX design and development with LibreChat's generative capabilities. Bring your ideas to life faster than ever before! +Use the fullscreen control in a rendered artifact preview to expand it to the complete browser display. The control follows browser Fullscreen API state, exits normally with Escape or browser controls, and is hidden when fullscreen is unavailable. + +Mermaid diagrams appear as compact inline cards that can open in the artifact panel. Export a diagram as SVG or PNG from either the inline card or the panel. Mermaid previews render directly rather than loading the Sandpack bundler; PNG export applies bounded canvas dimensions to protect the browser from oversized diagrams. ## Content-Security-Policy @@ -65,9 +78,3 @@ Self-hosting the bundler introduces some additional overhead: - **Resource Requirements**: Additional server resources will be needed to host the bundler For detailed instructions on setting up and maintaining your self-hosted bundler, refer to the [forked CodeSandbox repository](https://github.com/LibreChat-AI/codesandbox-client) tailored for LibreChat deployment, including the removal of telemetry from Sandpack. - ---- - -AI News 2024: The Original and BEST Open-Source AI Chat Platform, LibreChat Releases Code Artifacts! This Generative UI Tool Can Generate React, HTML & Diagrams Instantly from a Single Prompt in Your Browser with Any LLM, OpenAI, Anthropic, LLAMA, Mistral, DeepSeek Coder & More Thanks to OLLAMA Integration. - -#AINews2024 #OpenSourceAI #GenerativeUI #CodeArtifacts #WebDevelopment #ReactJS #LLM #AIPrototyping #DevTools #OLLAMA #LibreChat diff --git a/content/docs/features/code_interpreter.mdx b/content/docs/features/code_interpreter.mdx index a35594128..b37e83919 100644 --- a/content/docs/features/code_interpreter.mdx +++ b/content/docs/features/code_interpreter.mdx @@ -39,6 +39,8 @@ Execute code in multiple programming languages: - Secure file management - Session-based file organization +LibreChat restores referenced conversation files into the current Code Interpreter environment before an Agent run. If every required Code Interpreter file fails recovery, the run stops before model invocation and asks the user to reattach the files rather than continuing with stale references. + ### Security & Convenience - Secure sandboxed execution environment @@ -52,6 +54,24 @@ Programmatic Tool Calling lets LibreChat Agents route selected MCP tools through The sandbox still does not receive general network access. Tool calls are brokered through the Code Interpreter Tool Call Server and LibreChat's registered tool map, so only tools available to the agent can be called. +### Background Code Execution + +Background execution lets an Agent dispatch long-running code or shell work, continue the conversation, and retrieve the result later through `check_background_task`. In LibreChat chat, when the work finishes, stdout and generated files appear on the original code call. Generated files are persisted for subsequent turns even if the Agent has not polled the task yet. + +This feature is opt-in at the deployment level. Add `run_in_background` alongside `execute_code` in the [Agents endpoint capabilities](/docs/configuration/librechat_yaml/object_structure/agents#capabilities), then enable Code Interpreter on the agent. Code execution and shell calls become background-eligible automatically; turn off **Background execution** in the Code Interpreter tool settings when an agent should opt out. The model still decides per call whether to dispatch eligible work in the background. + +Background task state is process-local and does not survive an app restart or move between replicas. Background dispatch also does not extend the Code Interpreter service's execution limit; the deployment's normal server-side timeout still applies. + +### Stateful Code Sessions + +Stateful code sessions let a LibreChat Agent reuse one Code Interpreter sandbox workspace per conversation. Files, installed packages, and working state usually carry over between executions, making iterative analysis and multi-step file generation more efficient. + + + Stateful Code Sessions are in an early experimentation phase. Their behavior, configuration, persistence characteristics, and underlying integration may change substantially. Do not treat the current implementation as a stable production contract. + + +This feature is opt-in. Enable `execute_code` and `stateful_code_sessions` in the [Agents endpoint capabilities](/docs/configuration/librechat_yaml/object_structure/agents#capabilities), enable Code Interpreter on the agent, then turn on **Stateful code sessions** in its Advanced settings. The workspace may reset at any time. Save important outputs under `/mnt/data`, and do not otherwise rely on session state as durable storage. + ## Using the API ### In LibreChat @@ -64,6 +84,10 @@ The API has first-class support in LibreChat through these main methods: 3. **[Programmatic Tool Calling](/docs/features/agents#programmatic-tool-calling)**: Enable the `programmatic_tools` capability and mark selected MCP tools as Programmatic so agents can orchestrate those tools from sandboxed code. +4. **[Background Tool Calls](/docs/features/agents#background-tool-calls)**: Let an agent dispatch eligible code in the background and continue while it runs. + +5. **[Stateful Code Sessions](/docs/features/agents#stateful-code-sessions)**: Experimentally reuse a per-conversation workspace across an agent's code executions. + ![Code Interpreter in LibreChat](/images/agents/run_code.png) ### Set up API key @@ -96,12 +120,19 @@ Set the `LIBRECHAT_CODE_BASEURL` environment variable to point LibreChat at your - Upload input files - Download generated outputs -- Preview generated Office, CSV, text, and PDF-like artifacts inline when LibreChat can safely extract/render them +- Preview generated Office files, including PowerPoint `.pptx` presentations and `.potx` templates, plus CSV, text, and PDF-like artifacts inline when LibreChat can safely extract/render them +- Display PNG, JPEG, GIF, and WebP images returned by an Agent's `read_file` tool as viewable artifacts - List available files - Delete unnecessary files - Manage file sessions -Generated artifact previews are intentionally size-bounded. Set `FILE_PREVIEW_MAX_EXTRACT_BYTES` in LibreChat's `.env` to change the source-file size limit for inline preview extraction; larger files remain available for download. +Generated artifact previews are intentionally size-bounded. Set [`FILE_PREVIEW_MAX_EXTRACT_BYTES`](/docs/configuration/dotenv#inline-file-previews) in LibreChat's `.env` to change the source-file size limit for inline preview extraction; larger files remain available for download. + +Sandbox images returned through `read_file` have a 1 MiB inline limit. Larger images remain in the sandbox for processing with `bash_tool`. `LIBRECHAT_CODE_IMAGE_CHUNK_BYTES` controls only the transport chunk size used while reading eligible images; it does not raise the inline limit. + + + Deployments that regenerated the same Code Interpreter filename before the unique output-file index was added may have duplicate MongoDB records that prevent the index from building. Preview the repair with `npm run migrate:code-file-duplicates:dry-run`, then apply it with `npm run migrate:code-file-duplicates`. The migration keeps the newest canonical filename, renames older records with numeric suffixes, and builds the unique index after a successful run. + ### Limitations - Code cannot access the network diff --git a/content/docs/features/mcp.mdx b/content/docs/features/mcp.mdx index af6e92ddf..64b1635c9 100644 --- a/content/docs/features/mcp.mdx +++ b/content/docs/features/mcp.mdx @@ -61,9 +61,9 @@ mcpServers: MCP servers integrate seamlessly with LibreChat Agents: 1. Create or edit an agent -2. Click "Add MCP Server Tools" to open the Tools Dialog from the Agent Builder panel -3. Select MCP servers once added, each appears as a single entry -4. Fine-tune your agent's capabilites by enabling/disabling individual tools after adding +2. Open **Add tools** in the Agent Builder and select **MCP** +3. Select an MCP server; each server appears as a single catalog entry +4. Expand the selected server to enable or disable individual tools 5. Save your agent ![MCP Tools in Agent Builder](/images/mcp/mcp_ui_agent.png) @@ -165,6 +165,8 @@ When adding an MCP server through the UI, you can require users to provide their Behind the scenes, LibreChat automatically creates a `customUserVars` entry named `MCP_API_KEY` and configures the appropriate header template (e.g., `Authorization: Bearer {{MCP_API_KEY}}`). Each user provides their own key through the MCP Tool Select Dialog when configuring an agent โ€” the same UI used for [YAML-defined `customUserVars`](#user-provided-credentials). +When an administrator or user API key is configured, LibreChat treats the server as API-key authenticated and skips OAuth auto-detection. An explicit OAuth configuration still takes precedence. If a UI-created API-key server was saved by an older LibreChat version and remains stuck in **OAuth Required**, edit and save the server once so its stored connection metadata is refreshed. + For security, UI-created (DB-sourced) MCP servers can **only** resolve `customUserVars` placeholders (`{{VAR_NAME}}`). Server-side environment variables (`${ENV_VAR}`), user profile fields (`{{LIBRECHAT_USER_*}}`), and OIDC tokens (`{{LIBRECHAT_OPENID_*}}`) are intentionally blocked to prevent unauthorized access to server secrets or other users' data. For full placeholder support, configure the server in `librechat.yaml` instead. @@ -210,6 +212,7 @@ For detailed configuration options and examples, see: - [MCP Servers Configuration](/docs/configuration/librechat_yaml/object_structure/mcp_servers) - [Agent Configuration](/docs/configuration/librechat_yaml/object_structure/agents) - [Advanced Agent Features](/docs/features/agents#model-context-protocol-mcp) +- [Agent Plugins](/docs/features/agent_plugins) for experimentally bundling deployment MCP servers with Skills ## MCP Server Management @@ -254,6 +257,16 @@ You can initialize or re-initialize MCP servers directly from the interface: