Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(chat): persist explicit reply language per conversation

Bingxi Zhao (Frank)f363e5f119c1
diff --git a/deeptutor/agents/loop/pipeline.py b/deeptutor/agents/loop/pipeline.py
index b5b5a9c52..7e347e5c4 100644
--- a/deeptutor/agents/loop/pipeline.py
+++ b/deeptutor/agents/loop/pipeline.py
@@ -455,7 +455,10 @@ class AgenticLoopPipeline:
stable_blocks, self._runtime_snapshots = self._prompt_assembler.split_for_replay(
self._last_prompt_blocks
)
- return self._prompt_assembler.render(stable_blocks)
+ return self._prompt_assembler.render(
+ stable_blocks,
+ allow_user_override=not bool(context.metadata.get("reply_language_fixed")),
+ )
def _build_loop_messages(
self,
diff --git a/deeptutor/agents/loop/prompt_blocks.py b/deeptutor/agents/loop/prompt_blocks.py
index bbd298c88..47cb7473b 100644
--- a/deeptutor/agents/loop/prompt_blocks.py
+++ b/deeptutor/agents/loop/prompt_blocks.py
@@ -77,7 +77,7 @@ class LoopPromptAssembler:
)
)
- def render(self, blocks: list[PromptBlock]) -> str:
+ def render(self, blocks: list[PromptBlock], *, allow_user_override: bool = True) -> str:
"""Join assembled blocks into the system prompt string.
Split out of :meth:`system_prompt` so a caller that also needs the
@@ -88,11 +88,12 @@ class LoopPromptAssembler:
joined = "\n\n---\n\n".join(
f"## {block.name}\n{block.content.strip()}" for block in blocks if block.content.strip()
)
- # ``allow_user_override`` only here: chat has a user who can ask for a
- # different language mid-conversation, and the strict directive plus
- # the runtime policy above it otherwise make the model refuse them.
- # Books, quizzes and research keep the strict form — nobody is asking.
- return append_language_directive(joined, self.output_language, allow_user_override=True)
+ # Account defaults can yield to an explicit user request. A fixed
+ # conversation selector keeps the strict directive instead, so later
+ # turns cannot drift away from the selected language.
+ return append_language_directive(
+ joined, self.output_language, allow_user_override=allow_user_override
+ )
def split_for_replay(
self, blocks: list[PromptBlock]
diff --git a/deeptutor/api/routers/sessions.py b/deeptutor/api/routers/sessions.py
index 61f5e6326..9aa42b647 100644
--- a/deeptutor/api/routers/sessions.py
+++ b/deeptutor/api/routers/sessions.py
@@ -12,6 +12,7 @@ from fastapi import APIRouter, HTTPException, Query, Request
from pydantic import BaseModel, Field, field_validator
from deeptutor.learning.storage import LearningStore
+from deeptutor.response_languages import validate_reply_language_override
from deeptutor.services.session import get_session_store, get_sqlite_session_store
from deeptutor.services.session.organization import (
list_all_sessions_snapshot,
@@ -53,6 +54,15 @@ class SessionOrganizationRequest(BaseModel):
archived: bool | None = None
+class SessionReplyLanguageRequest(BaseModel):
+ language: str | None
+
+ @field_validator("language")
+ @classmethod
+ def _supported_language(cls, value: str | None) -> str | None:
+ return validate_reply_language_override(value)
+
+
class QuizResultItem(BaseModel):
question_id: str = ""
question: str = Field(..., min_length=1)
@@ -242,6 +252,21 @@ async def rename_session(session_id: str, payload: SessionRenameRequest):
return {"session": session}
[email protected]("/{session_id}/reply-language")
+async def update_session_reply_language(session_id: str, payload: SessionReplyLanguageRequest):
+ """Fix this conversation's reply language, or return to the account default."""
+ store = get_session_store()
+ if await store.get_session(session_id) is None:
+ raise HTTPException(status_code=404, detail="Session not found")
+ updated = await store.update_session_preferences(
+ session_id, {"reply_language_override": payload.language}
+ )
+ session = await store.get_session(session_id)
+ if not updated or session is None:
+ raise HTTPException(status_code=404, detail="Session not found")
+ return {"session": session}
+
+
@router.patch("/{session_id}/organization")
async def update_session_organization(
session_id: str, payload: SessionOrganizationRequest, request: Request = None
diff --git a/deeptutor/core/turn_request.py b/deeptutor/core/turn_request.py
index fc5f91ad2..166a0343a 100644
--- a/deeptutor/core/turn_request.py
+++ b/deeptutor/core/turn_request.py
@@ -5,7 +5,9 @@ from __future__ import annotations
from typing import Any, Literal
import warnings
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from deeptutor.response_languages import validate_reply_language_override
_LEGACY_RUNTIME_CONFIG_KEYS: dict[str, str] = {
"_persist_user_message": "persist_user_message",
@@ -124,6 +126,9 @@ class TurnRequest(BaseModel):
tools: list[str] | None = None
knowledge_bases: list[str] = Field(default_factory=list)
language: str | None = None
+ # Only an explicit session selector sets this. Omitted means keep the
+ # conversation's override; null returns it to the account default.
+ reply_language_override: str | None = None
config: dict[str, Any] = Field(default_factory=dict)
notebook_references: list[NotebookReference] = Field(default_factory=list)
@@ -183,6 +188,11 @@ class TurnRequest(BaseModel):
partner_discussion_group_id: str | None = None
auto_route: bool | None = None
+ @field_validator("reply_language_override")
+ @classmethod
+ def _validate_reply_language_override(cls, value: str | None) -> str | None:
+ return validate_reply_language_override(value)
+
@model_validator(mode="before")
@classmethod
def _translate_legacy_runtime_config(cls, value: Any) -> Any:
diff --git a/deeptutor/response_languages.py b/deeptutor/response_languages.py
index 9e9e7a6ba..1bcde2693 100644
--- a/deeptutor/response_languages.py
+++ b/deeptutor/response_languages.py
@@ -16,3 +16,16 @@ SUPPORTED_RESPONSE_LANGUAGES: tuple[str, ...] = (
"pl",
"uk",
)
+
+
+def validate_reply_language_override(value: str | None) -> str | None:
+ """Validate a conversation override without changing its meaning.
+
+ ``None`` means follow the account default. A typo must fail visibly rather
+ than silently turning a fixed-language conversation back into default.
+ """
+ if value is None:
+ return None
+ if value not in SUPPORTED_RESPONSE_LANGUAGES:
+ raise ValueError("Unsupported reply language")
+ return value
diff --git a/deeptutor/services/session/turns/executor.py b/deeptutor/services/session/turns/executor.py
index 130e67fc1..dc2500601 100644
--- a/deeptutor/services/session/turns/executor.py
+++ b/deeptutor/services/session/turns/executor.py
@@ -914,6 +914,7 @@ class TurnExecutor:
"conversation_context_text": conversation_context_text,
"history_token_count": history_result.token_count,
"history_budget": history_result.budget,
+ "reply_language_fixed": bool(payload.get("_reply_language_fixed")),
"turn_id": turn_id,
"question_followup_context": followup_question_context or {},
"selection_tutor_context": selection_tutor_context or {},
diff --git a/deeptutor/services/session/turns/request_preparer.py b/deeptutor/services/session/turns/request_preparer.py
index aefe04c6c..1b6c20080 100644
--- a/deeptutor/services/session/turns/request_preparer.py
+++ b/deeptutor/services/session/turns/request_preparer.py
@@ -172,6 +172,17 @@ class TurnRequestPreparer:
session = await self.store.ensure_session(payload.get("session_id"))
preferences = session.get("preferences") or {}
+ # A conversation-level choice wins over the account default that the
+ # browser sends on every turn. Only the selector's explicit field may
+ # change or clear this durable override (#1511).
+ if "reply_language_override" in payload:
+ reply_language_override = payload["reply_language_override"]
+ else:
+ reply_language_override = preferences.get("reply_language_override")
+ if reply_language_override:
+ payload["language"] = reply_language_override
+ payload["_reply_language_fixed"] = bool(reply_language_override)
+
# Freeze the content binding at admission, before scheduling the turn.
# Existing conversations are moved through the organization endpoint;
# a stale tab must never move one by sending its cached preference.
@@ -554,6 +565,8 @@ class TurnRequestPreparer:
"knowledge_bases": list(payload.get("knowledge_bases") or []),
"language": str(payload.get("language") or "en"),
}
+ if "reply_language_override" in payload:
+ preference_update["reply_language_override"] = reply_language_override
if content_workspace_enabled and "workspace_id" not in preferences:
preference_update["workspace_id"] = content_workspace_id or None
# Missing legacy chat fields should not manufacture an empty stored
diff --git a/tests/services/prompt/test_language_directive.py b/tests/services/prompt/test_language_directive.py
index f29f816b5..079df92c6 100644
--- a/tests/services/prompt/test_language_directive.py
+++ b/tests/services/prompt/test_language_directive.py
@@ -52,6 +52,17 @@ def test_chat_renders_the_overridable_directive(language: str, marker: str) -> N
assert marker in rendered
+def test_fixed_session_selector_disables_conversational_override() -> None:
+ from deeptutor.agents.loop.prompt_blocks import LoopPromptAssembler, PromptBlock
+
+ assembler = LoopPromptAssembler(prompts={}, language="fr")
+ rendered = assembler.render(
+ [PromptBlock(name="Base", content="body")], allow_user_override=False
+ )
+ assert "Français" in rendered
+ assert "explicitly asks" not in rendered
+
+
@pytest.mark.parametrize(
("language", "label"),
[("fr", "Français"), ("uk", "Українська")],
diff --git a/tests/services/session/test_reply_language_override.py b/tests/services/session/test_reply_language_override.py
new file mode 100644
index 000000000..f060944c2
--- /dev/null
+++ b/tests/services/session/test_reply_language_override.py
@@ -0,0 +1,103 @@
+"""A conversation's explicit reply language survives later account defaults."""
+
+from __future__ import annotations
+
+from fastapi import HTTPException
+from pydantic import ValidationError
+import pytest
+
+from deeptutor.api.routers import sessions as sessions_router
+from deeptutor.core.turn_request import TurnRequest
+from deeptutor.services.session.sqlite_store import SQLiteSessionStore
+from deeptutor.services.session.turn_runtime import TurnRuntimeManager
+
+
+async def test_explicit_reply_language_stays_with_one_conversation(
+ monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+ store = SQLiteSessionStore(tmp_path / "reply-language.db")
+ runtime = TurnRuntimeManager(store)
+ languages: list[tuple[str, bool]] = []
+
+ async def capture_turn(execution) -> None:
+ languages.append(
+ (execution.payload["language"], execution.payload["_reply_language_fixed"])
+ )
+ await store.transition_turn(execution.turn_id, "completed")
+
+ monkeypatch.setattr(runtime, "_run_turn", capture_turn)
+ monkeypatch.setattr(sessions_router, "get_session_store", lambda: store)
+
+ async def send(session_id: str | None, account_language: str, **extra) -> str:
+ session, turn = await runtime.start_turn(
+ {
+ "session_id": session_id,
+ "content": "Explain this concept",
+ "language": account_language,
+ **extra,
+ }
+ )
+ await runtime._executions[turn["id"]].task
+ return session["id"]
+
+ # A Chinese question can be taught in French. A later English account
+ # setting must not reset the conversation; a different session still uses
+ # its own account default.
+ session_id = await send(None, "zh", reply_language_override="fr")
+ await send(session_id, "en")
+ assert languages == [("fr", True), ("fr", True)]
+ assert (await store.get_session(session_id))["preferences"]["reply_language_override"] == "fr"
+
+ other_id = await send(None, "ja")
+ assert other_id != session_id
+ assert languages[-1] == ("ja", False)
+
+ # Clearing the selector resumes the current account default, even if the
+ # session's last effective language was French.
+ await sessions_router.update_session_reply_language(
+ session_id, sessions_router.SessionReplyLanguageRequest(language=None)
+ )
+ await send(session_id, "zh")
+ assert languages[-1] == ("zh", False)
+ assert (await store.get_session(session_id))["preferences"]["reply_language_override"] is None
+
+
+ "code", ["en", "zh", "zh-tw", "ja", "ko", "es", "fr", "de", "ru", "pt", "it", "ar", "pl", "uk"]
+)
+def test_selector_accepts_every_supported_response_language(code: str) -> None:
+ assert TurnRequest(content="hi", reply_language_override=code).reply_language_override == code
+ assert sessions_router.SessionReplyLanguageRequest(language=code).language == code
+
+
[email protected]("value", ["", "xx", "French", "zh-CN", "__default__"])
+def test_invalid_selector_value_fails_instead_of_silently_falling_back(value: str) -> None:
+ with pytest.raises(ValidationError):
+ TurnRequest(content="hi", reply_language_override=value)
+ with pytest.raises(ValidationError):
+ sessions_router.SessionReplyLanguageRequest(language=value)
+
+
+def test_omitted_selector_is_distinct_from_explicit_default() -> None:
+ assert "reply_language_override" not in TurnRequest(content="hi").to_payload()
+ assert (
+ TurnRequest(content="hi", reply_language_override=None).to_payload()[
+ "reply_language_override"
+ ]
+ is None
+ )
+
+
+async def test_selector_does_not_create_a_missing_session(
+ monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+ store = SQLiteSessionStore(tmp_path / "reply-language-missing.db")
+ monkeypatch.setattr(sessions_router, "get_session_store", lambda: store)
+ with pytest.raises(HTTPException) as error:
+ await sessions_router.update_session_reply_language(
+ "missing", sessions_router.SessionReplyLanguageRequest(language="fr")
+ )
+ assert error.value.status_code == 404
+ assert await store.get_session("missing") is None
diff --git a/web/context/app-shell-storage.ts b/web/context/app-shell-storage.ts
index c82ccc830..bf76442fc 100644
--- a/web/context/app-shell-storage.ts
+++ b/web/context/app-shell-storage.ts
@@ -43,6 +43,11 @@ const SUPPORTED_RESPONSE_LANGUAGE_CODES: readonly ResponseLanguage[] = [
"uk",
];
+export function isResponseLanguage(value: unknown): value is ResponseLanguage {
+ return typeof value === "string" &&
+ (SUPPORTED_RESPONSE_LANGUAGE_CODES as readonly string[]).includes(value);
+}
+
const RESPONSE_LANGUAGE_ALIASES: Record<string, ResponseLanguage> = {
"simplified chinese": "zh",
"traditional chinese": "zh-tw",
diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.ts
index ce8bdb77b..9562048d5 100644
--- a/web/contracts/generated/api.ts
+++ b/web/contracts/generated/api.ts
@@ -7023,6 +7023,26 @@ export interface paths {
readonly patch?: never;
readonly trace?: never;
};
+ readonly "/api/sessions/{session_id}/reply-language": {
+ readonly parameters: {
+ readonly query?: never;
+ readonly header?: never;
+ readonly path?: never;
+ readonly cookie?: never;
+ };
+ readonly get?: never;
+ readonly put?: never;
+ readonly post?: never;
+ readonly delete?: never;
+ readonly options?: never;
+ readonly head?: never;
+ /**
+ * Update Session Reply Language
+ * @description Fix this conversation's reply language, or return to the account default.
+ */
+ readonly patch: operations["update_session_reply_language_api_sessions__session_id__reply_language_patch"];
+ readonly trace?: never;
+ };
readonly "/api/sessions/{session_id}/restore": {
readonly parameters: {
readonly query?: never;
@@ -14317,6 +14337,11 @@ export interface components {
/** Title */
readonly title: string;
};
+ /** SessionReplyLanguageRequest */
+ readonly SessionReplyLanguageRequest: {
+ /** Language */
+ readonly language: string | null;
+ };
/** SessionSummary */
readonly SessionSummary: {
/** @default null */
@@ -15036,6 +15061,11 @@ export interface components {
* @default null
*/
readonly regenerated_from_message_id: number | string | null;
+ /**
+ * Reply Language Override
+ * @default null
+ */
+ readonly reply_language_override: string | null;
/**
* Selection Tutor Context
* @default null
@@ -16286,6 +16316,8 @@ export type SchemaSessionOrganizationRequest =
components["schemas"]["SessionOrganizationRequest"];
export type SchemaSessionRenameRequest =
components["schemas"]["SessionRenameRequest"];
+export type SchemaSessionReplyLanguageRequest =
+ components["schemas"]["SessionReplyLanguageRequest"];
export type SchemaSessionSummary = components["schemas"]["SessionSummary"];
export type SchemaSetRoleRequest = components["schemas"]["SetRoleRequest"];
export type SchemaSetSessionModeRequest =
@@ -32228,6 +32260,45 @@ export interface operations {
};
};
};
+ readonly update_session_reply_language_api_sessions__session_id__reply_language_patch: {
+ readonly parameters: {
+ readonly query?: never;
+ readonly header?: {
+ readonly Authorization?: string | null;
+ };
+ readonly path: {
+ readonly session_id: string;
+ };
+ readonly cookie?: {
+ readonly dt_token?: string | null;
+ };
+ };
+ readonly requestBody: {
+ readonly content: {
+ readonly "application/json": components["schemas"]["SessionReplyLanguageRequest"];
+ };
+ };
+ readonly responses: {
+ /** @description Successful Response */
+ readonly 200: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": unknown;
+ };
+ };
+ /** @description Validation Error */
+ readonly 422: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": components["schemas"]["HTTPValidationError"];
+ };
+ };
+ };
+ };
readonly restore_session_api_sessions__session_id__restore_post: {
readonly parameters: {
readonly query?: never;
diff --git a/web/contracts/generated/turn-protocol.ts b/web/contracts/generated/turn-protocol.ts
index efc920d1d..ca184381f 100644
--- a/web/contracts/generated/turn-protocol.ts
+++ b/web/contracts/generated/turn-protocol.ts
@@ -74,6 +74,7 @@ export type Selection = string | null;
export type ReadingWorkspaceId = string | null;
export type Regenerate = boolean;
export type RegeneratedFromMessageId = number | string | null;
+export type ReplyLanguageOverride = string | null;
export type SelectionTutorContext = {
[k: string]: unknown;
} | null;
@@ -308,6 +309,7 @@ export interface StartTurnCommand {
reading_workspace_id?: ReadingWorkspaceId;
regenerate?: Regenerate;
regenerated_from_message_id?: RegeneratedFromMessageId;
+ reply_language_override?: ReplyLanguageOverride;
selection_tutor_context?: SelectionTutorContext;
session_id?: SessionId;
skills?: Skills;
diff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.json
index cefa70e9d..4b7e844a0 100644
--- a/web/contracts/schema/openapi.json
+++ b/web/contracts/schema/openapi.json
@@ -8742,6 +8742,26 @@
"title": "SessionRenameRequest",
"type": "object"
},
+ "SessionReplyLanguageRequest": {
+ "properties": {
+ "language": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Language"
+ }
+ },
+ "required": [
+ "language"
+ ],
+ "title": "SessionReplyLanguageRequest",
+ "type": "object"
+ },
"SessionSummary": {
"additionalProperties": false,
"properties": {
@@ -10309,6 +10329,18 @@
"default": null,
"title": "Regenerated From Message Id"
},
+ "reply_language_override": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Reply Language Override"
+ },
"selection_tutor_context": {
"anyOf": [
{
@@ -45873,6 +45905,89 @@
]
}
},
+ "/api/sessions/{session_id}/reply-language": {
+ "patch": {
+ "description": "Fix this conversation's reply language, or return to the account default.",
+ "operationId": "update_session_reply_language_api_sessions__session_id__reply_language_patch",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "session_id",
+ "required": true,
+ "schema": {
+ "title": "Session Id",
+ "type": "string"
+ }
+ },
+ {
+ "in": "header",
+ "name": "Authorization",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Authorization"
+ }
+ },
+ {
+ "in": "cookie",
+ "name": "dt_token",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Dt Token"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionReplyLanguageRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "Successful Response"
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ "description": "Validation Error"
+ }
+ },
+ "summary": "Update Session Reply Language",
+ "tags": [
+ "sessions"
+ ]
+ }
+ },
"/api/sessions/{session_id}/restore": {
"post": {
"operationId": "restore_session_api_sessions__session_id__restore_post",
diff --git a/web/contracts/schema/turn-protocol.json b/web/contracts/schema/turn-protocol.json
index 74848b4fd..3a0a131a6 100644
--- a/web/contracts/schema/turn-protocol.json
+++ b/web/contracts/schema/turn-protocol.json
@@ -1154,6 +1154,18 @@
"default": null,
"title": "Regenerated From Message Id"
},
+ "reply_language_override": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Reply Language Override"
+ },
"selection_tutor_context": {
"anyOf": [
{
diff --git a/web/features/chat/ChatStateAdapter.tsx b/web/features/chat/ChatStateAdapter.tsx
index 2edb062f8..81ff13372 100644
--- a/web/features/chat/ChatStateAdapter.tsx
+++ b/web/features/chat/ChatStateAdapter.tsx
@@ -16,9 +16,10 @@ import type { ClientCommand } from "@/contracts/generated/turn-protocol";
import {
RESPONSE_LANGUAGE_EVENT,
RESPONSE_LANGUAGE_STORAGE_KEY,
- normalizeLanguage,
+ isResponseLanguage,
readStoredChatResponseTimeout,
readStoredResponseLanguage,
+ resolveResponseLanguage,
writeStoredActiveSessionId,
} from "@/context/app-shell-storage";
import type {
@@ -34,6 +35,7 @@ import {
deleteMessage,
updateBranchSelection,
updateSessionTitle,
+ updateSessionReplyLanguage,
type MessageTracePage,
type SessionMessage,
} from "@/lib/session-api";
@@ -182,6 +184,8 @@ export interface ChatState {
isStreaming: boolean;
currentStage: string;
language: string;
+ /** Explicit conversation choice; null follows the account reply language. */
+ replyLanguageOverride: string | null;
/** Edit-branching: keyed by stringified parent_message_id (or "null"
* for the root). Empty means "default to latest sibling everywhere". */
selectedBranches: Record<string, number>;
@@ -320,6 +324,7 @@ interface SessionSnapshot {
personaSelection?: string;
resourceSelection?: ResourceSelection;
language?: string;
+ replyLanguageOverride?: string | null;
selectedBranches?: Record<string, number>;
}
@@ -337,6 +342,7 @@ type Action =
| { type: "SET_PERSONA_SELECTION"; persona: string }
| { type: "SET_RESOURCE_SELECTION"; selection: ResourceSelection }
| { type: "SET_LANGUAGE"; lang: string }
+ | { type: "SET_REPLY_LANGUAGE_OVERRIDE"; key: string; language: string | null }
| {
type: "ADD_USER_MSG";
key: string;
@@ -438,6 +444,7 @@ function createSessionEntry(
currentStage: "",
language:
typeof window === "undefined" ? "en" : readStoredResponseLanguage(),
+ replyLanguageOverride: null,
status: "idle",
activeTurnId: null,
lastSeq: 0,
@@ -623,8 +630,23 @@ function reducer(state: ProviderState, action: Action): ProviderState {
case "SET_LANGUAGE":
return updateSelectedSession(state, (session) => ({
...session,
- language: action.lang,
+ language: session.replyLanguageOverride ?? action.lang,
}));
+ case "SET_REPLY_LANGUAGE_OVERRIDE": {
+ const session = state.sessions[action.key];
+ if (!session) return state;
+ return {
+ ...state,
+ sessions: {
+ ...state.sessions,
+ [action.key]: {
+ ...session,
+ replyLanguageOverride: action.language,
+ language: action.language ?? readStoredResponseLanguage(),
+ },
+ },
+ };
+ }
case "ADD_USER_MSG": {
const session =
state.sessions[action.key] ?? createSessionEntry(action.key);
@@ -1015,6 +1037,10 @@ function reducer(state: ProviderState, action: Action): ProviderState {
lastSeq: 0,
status: action.status || "idle",
language: action.language ?? existing.language,
+ replyLanguageOverride:
+ action.replyLanguageOverride !== undefined
+ ? action.replyLanguageOverride
+ : existing.replyLanguageOverride,
selectedBranches:
action.selectedBranches ?? existing.selectedBranches,
updatedAt: Date.now(),
@@ -1284,6 +1310,7 @@ interface ChatContextValue {
setPersonaSelection: (persona: string) => void;
setResourceSelection: (selection: ResourceSelection) => void;
setLanguage: (lang: string) => void;
+ setReplyLanguageOverride: (language: string | null) => Promise<void>;
sendMessage: (
content: string,
attachments?: OutgoingAttachment[],
@@ -2127,6 +2154,11 @@ export function ChatStateAdapterProvider({
session.preferences?.workspace_mode,
session.preferences?.capability,
);
+ const replyLanguageOverride = isResponseLanguage(
+ session.preferences?.reply_language_override,
+ )
+ ? session.preferences.reply_language_override
+ : null;
// A stored `running` is only believable while it is recent — see
// `resolveLoadedRunStatus`. A turn the backend never got to close out
// (crash, restart) would otherwise open the conversation into a
@@ -2194,10 +2226,10 @@ export function ChatStateAdapterProvider({
skills: asStringArray(session.preferences?.skills),
mcp: asStringArray(session.preferences?.mcp),
},
- // Model output language is account-level state. Historical sessions
- // may have stale persisted preferences, so new turns follow the
- // current response-language setting rather than their original value.
- language: readStoredResponseLanguage(),
+ // Historical `preferences.language` is only the last turn's account
+ // default. The dedicated selector is the durable conversation choice.
+ language: replyLanguageOverride ?? readStoredResponseLanguage(),
+ replyLanguageOverride,
selectedBranches: normalizeSelectedBranches(
session.preferences?.selected_branches,
),
@@ -2235,7 +2267,10 @@ export function ChatStateAdapterProvider({
if (typeof window === "undefined") return;
const syncLanguage = (language: string | null | undefined) => {
- dispatch({ type: "SET_LANGUAGE", lang: normalizeLanguage(language) });
+ dispatch({
+ type: "SET_LANGUAGE",
+ lang: resolveResponseLanguage(language, readStoredResponseLanguage()),
+ });
};
const onResponseLanguage = (event: Event) => {
const detail = (event as CustomEvent<{ language?: string }>).detail;
@@ -2357,7 +2392,9 @@ export function ChatStateAdapterProvider({
const effectiveMasterySessionMode =
replaySnapshot?.masterySessionMode ?? session.masterySessionMode;
const effectiveLanguage =
- replaySnapshot?.language ?? readStoredResponseLanguage();
+ replaySnapshot?.language ??
+ session.replyLanguageOverride ??
+ readStoredResponseLanguage();
// Persona resolution: replay snapshot wins; then an explicit per-call
// persona (quiz follow-up surface); then the session-level preference.
// Always a string — "" means Default / no persona.
@@ -2547,6 +2584,11 @@ export function ChatStateAdapterProvider({
autoRoute: typeof autoRoute === "boolean" ? autoRoute : null,
attachments: effectiveAttachments,
language: effectiveLanguage,
+ // A draft has no session to PATCH yet. Persist its selector with the
+ // first turn; existing sessions use their server-side preference.
+ ...(!session.sessionId && session.replyLanguageOverride
+ ? { replyLanguageOverride: session.replyLanguageOverride }
+ : {}),
notebookReferences: effectiveNotebookReferences,
historyReferences: effectiveHistoryReferences,
questionNotebookReferences: effectiveQuestionNotebookReferences,
@@ -2809,6 +2851,7 @@ export function ChatStateAdapterProvider({
isStreaming: current.isStreaming,
currentStage: current.currentStage,
language: current.language,
+ replyLanguageOverride: current.replyLanguageOverride,
selectedBranches: current.selectedBranches,
lastTurnFailed: isFailedTurnVisible(
current.messages,
@@ -2877,6 +2920,32 @@ export function ChatStateAdapterProvider({
dispatch({ type: "SET_LANGUAGE", lang });
}, []);
+ const setReplyLanguageOverride = useCallback(async (language: string | null) => {
+ if (language !== null && !isResponseLanguage(language)) {
+ throw new Error("Unsupported reply language");
+ }
+ const currentState = stateRef.current;
+ const key = currentState.selectedKey;
+ if (!key) return;
+ const session = currentState.sessions[key];
+ if (!session) return;
+ if (!session.sessionId) {
+ dispatch({ type: "SET_REPLY_LANGUAGE_OVERRIDE", key, language });
+ return;
+ }
+ const updated = await updateSessionReplyLanguage(
+ session.sessionId,
+ language,
+ session.workspaceId ?? undefined,
+ );
+ const saved = updated.preferences?.reply_language_override;
+ dispatch({
+ type: "SET_REPLY_LANGUAGE_OVERRIDE",
+ key,
+ language: isResponseLanguage(saved) ? saved : null,
+ });
+ }, []);
+
const renameSessionTitle = useCallback(async (title: string) => {
const trimmed = title.trim();
if (!trimmed) return;
@@ -3048,6 +3117,7 @@ export function ChatStateAdapterProvider({
setPersonaSelection,
setResourceSelection,
setLanguage,
+ setReplyLanguageOverride,
sendMessage,
cancelStreamingTurn,
submitUserReply,
@@ -3079,6 +3149,7 @@ export function ChatStateAdapterProvider({
setPersonaSelection,
setResourceSelection,
setLanguage,
+ setReplyLanguageOverride,
sendMessage,
cancelStreamingTurn,
submitUserReply,
diff --git a/web/features/chat/components/ChatWorkspace.tsx b/web/features/chat/components/ChatWorkspace.tsx
index 27d14833c..8b7faef0a 100644
--- a/web/features/chat/components/ChatWorkspace.tsx
+++ b/web/features/chat/components/ChatWorkspace.tsx
@@ -25,6 +25,7 @@ import {
useState,
} from "react";
import { useChatRouteSession } from "@/features/chat/controllers/useChatRouteSession";
+import { waitForReplyLanguageSave } from "@/features/chat/controllers/reply-language-save";
import {
GraduationCap,
@@ -70,6 +71,8 @@ import {
type MessageRequestSnapshot,
} from "@/features/chat/ChatStateAdapter";
import { useAppShell } from "@/context/AppShellContext";
+import { readStoredResponseLanguage } from "@/context/app-shell-storage";
+import { RESPONSE_LANGUAGE_OPTIONS } from "@/features/settings/store";
import { WATCHING_ASK_EVENT } from "@/components/watching/WatchingPane";
import type { FilePreviewSource } from "@/components/chat/preview/previewerFor";
@@ -278,6 +281,7 @@ export default function ChatWorkspace({
setLLMSelection,
setPersonaSelection,
setResourceSelection,
+ setReplyLanguageOverride,
sendMessage,
cancelStreamingTurn,
submitUserReply,
@@ -296,6 +300,25 @@ export default function ChatWorkspace({
} = useChatStateAdapter();
const entrySessionId = useRef(state.sessionId);
+ const [replyLanguageSavingKey, setReplyLanguageSavingKey] = useState<string | null>(null);
+ const replyLanguageSaveRef = useRef<{ key: string; pending: Promise<void> } | null>(null);
+ const handleReplyLanguageChange = useCallback((value: string) => {
+ const language = value || null;
+ const key = state.sessionKey;
+ const pending = setReplyLanguageOverride(language);
+ replyLanguageSaveRef.current = { key, pending };
+ setReplyLanguageSavingKey(key);
+ void pending
+ .catch((error: unknown) => {
+ notify(error instanceof Error ? error.message : t("Action failed"));
+ })
+ .finally(() => {
+ if (replyLanguageSaveRef.current?.pending === pending) {
+ replyLanguageSaveRef.current = null;
+ setReplyLanguageSavingKey(null);
+ }
+ });
+ }, [setReplyLanguageOverride, state.sessionKey, t]);
const resourceReuse = useResourceReusePolicy(state.sessionKey || "draft", state.messages[0]?.id);
const [knowledgeBases, setKnowledgeBases] = useState<KnowledgeBase[]>([]);
@@ -1865,6 +1888,15 @@ export default function ChatWorkspace({
const handleSend = useCallback(
async (content: string) => {
+ // An existing session saves its selector before the next turn starts.
+ // The composer may be used immediately after changing the dropdown.
+ if (!(await waitForReplyLanguageSave(
+ replyLanguageSaveRef.current?.key === state.sessionKey
+ ? replyLanguageSaveRef.current.pending
+ : null,
+ content,
+ (draft) => prefillInputRef.current?.(draft),
+ ))) return;
// A turn paused on a question: what the user typed is their answer, not
// a new message. Routing it here means the card is one way to answer,
// not the only one — and a card that never rendered no longer strands
@@ -2044,6 +2076,7 @@ export default function ChatWorkspace({
sendMessage,
shouldAutoScrollRef,
state.isStreaming,
+ state.sessionKey,
subagentBudget,
selectedPartnerGroup,
selectedPartner,
@@ -2473,6 +2506,27 @@ export default function ChatWorkspace({
</span>
) : null}
</div>
+ <label className="flex shrink-0 items-center gap-1.5 text-[11px] text-[var(--muted-foreground)]">
+ <span className="hidden sm:inline">{t("Reply language")}</span>
+ <select
+ aria-label={t("Reply language")}
+ value={state.replyLanguageOverride ?? ""}
+ onChange={(event) => handleReplyLanguageChange(event.target.value)}
+ disabled={replyLanguageSavingKey === state.sessionKey || state.isStreaming}
+ className="max-w-[170px] rounded-lg border border-[var(--border)] bg-[var(--background)] px-2 py-1 text-[11px] text-[var(--foreground)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)] disabled:opacity-50"
+ >
+ <option value="">
+ {t("Account default")} ({RESPONSE_LANGUAGE_OPTIONS.find(
+ (option) => option.value === readStoredResponseLanguage(),
+ )?.label ?? "English"})
+ </option>
+ {RESPONSE_LANGUAGE_OPTIONS.map((option) => (
+ <option key={option.value} value={option.value}>
+ {option.label}
+ </option>
+ ))}
+ </select>
+ </label>
<div className="flex shrink-0 items-center gap-0.5">
<HeaderActionButton
onClick={() => setShowSaveModal(true)}
diff --git a/web/features/chat/controllers/buildStartTurnInput.ts b/web/features/chat/controllers/buildStartTurnInput.ts
index e60047a9e..08802e9cb 100644
--- a/web/features/chat/controllers/buildStartTurnInput.ts
+++ b/web/features/chat/controllers/buildStartTurnInput.ts
@@ -75,6 +75,9 @@ export function buildStartTurnInput(input: StartTurnInput): StartTurnCommand {
tools: input.tools ?? null,
knowledge_bases: input.knowledgeBases ?? [],
language: input.language ?? null,
+ ...(input.replyLanguageOverride !== undefined
+ ? { reply_language_override: input.replyLanguageOverride }
+ : {}),
config: capabilityConfig(input),
attachments: input.attachments ?? [],
notebook_references: input.notebookReferences ?? [],
diff --git a/web/features/chat/controllers/reply-language-save.ts b/web/features/chat/controllers/reply-language-save.ts
new file mode 100644
index 000000000..7be5d40b8
--- /dev/null
+++ b/web/features/chat/controllers/reply-language-save.ts
@@ -0,0 +1,15 @@
+/** Keep a composer draft if its session language could not be saved. */
+export async function waitForReplyLanguageSave(
+ pending: Promise<void> | null,
+ content: string,
+ restoreDraft: (content: string) => void,
+): Promise<boolean> {
+ if (!pending) return true;
+ try {
+ await pending;
+ return true;
+ } catch {
+ restoreDraft(content);
+ return false;
+ }
+}
diff --git a/web/features/chat/model/start-turn.ts b/web/features/chat/model/start-turn.ts
index 9f7e400a8..9050c6aee 100644
--- a/web/features/chat/model/start-turn.ts
+++ b/web/features/chat/model/start-turn.ts
@@ -19,6 +19,8 @@ export interface StartTurnInput {
tools?: string[] | null;
knowledgeBases?: string[];
language?: string | null;
+ /** Omit to preserve the session's selector; null explicitly clears it. */
+ replyLanguageOverride?: string | null;
capabilityConfig?: Record<string, unknown>;
allowedCapabilityConfigKeys?: readonly string[];
attachments?: OutgoingAttachment[];
diff --git a/web/lib/session-api.ts b/web/lib/session-api.ts
index 24ffb6853..671fc5150 100644
--- a/web/lib/session-api.ts
+++ b/web/lib/session-api.ts
@@ -73,6 +73,8 @@ export interface SessionPreferences {
tools?: string[];
knowledge_bases?: string[];
language?: string;
+ /** Null/absent follows the account default; a code fixes this conversation. */
+ reply_language_override?: string | null;
llm_selection?: LLMSelection | null;
/** Persistent mastery state associated with this conversation. */
mastery_path_id?: string;
@@ -302,6 +304,24 @@ export async function updateSessionTitle(
return data.session;
}
+export async function updateSessionReplyLanguage(
+ sessionId: string,
+ language: string | null,
+ workspaceId?: string,
+): Promise<{ preferences?: SessionPreferences }> {
+ const response = await apiFetch(
+ apiUrl(scopedUrl(`/api/sessions/${sessionId}/reply-language`, workspaceId)),
+ {
+ method: "PATCH",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ language }),
+ },
+ );
+ const data = await expectJson<{ session: { preferences?: SessionPreferences } }>(response);
+ invalidateClientCache("sessions:");
+ return data.session;
+}
+
export async function getMessageTrace(
sessionId: string,
messageId: number,
diff --git a/web/locales/en/app.json b/web/locales/en/app.json
index ffecc6c11..36a7f01c5 100644
--- a/web/locales/en/app.json
+++ b/web/locales/en/app.json
@@ -222,6 +222,7 @@
"LLM Configuration": "LLM Configuration",
"Configure web search providers": "Configure web search providers",
"Default": "Default",
+ "Account default": "Account default",
"Test": "Test",
"Edit": "Edit",
"Delete": "Delete",
diff --git a/web/locales/fr/app.json b/web/locales/fr/app.json
index 165b156ac..99db89020 100644
--- a/web/locales/fr/app.json
+++ b/web/locales/fr/app.json
@@ -234,6 +234,7 @@
"Configure web search providers": "Configurer les fournisseurs de recherche web",
"Add Configuration": "Ajouter une configuration",
"Default": "Par défaut",
+ "Account default": "Valeur par défaut du compte",
"Set Active": "Activer",
"Test": "Tester",
"Edit": "Modifier",
diff --git a/web/locales/uk/app.json b/web/locales/uk/app.json
index 1b02159d6..11812faf3 100644
--- a/web/locales/uk/app.json
+++ b/web/locales/uk/app.json
@@ -211,6 +211,7 @@
"LLM Configuration": "Налаштування LLM",
"Configure web search providers": "Налаштувати провайдерів веб-пошуку",
"Default": "За замовчуванням",
+ "Account default": "Типова мова облікового запису",
"Test": "Тест",
"Edit": "Редагувати",
"Delete": "Видалити",
diff --git a/web/locales/zh/app.json b/web/locales/zh/app.json
index a5e0abcde..7d988b13f 100644
--- a/web/locales/zh/app.json
+++ b/web/locales/zh/app.json
@@ -222,6 +222,7 @@
"LLM Configuration": "LLM 配置",
"Configure web search providers": "配置网络搜索提供商",
"Default": "默认",
+ "Account default": "账户默认",
"Test": "测试",
"Edit": "编辑",
"Delete": "删除",
diff --git a/web/tests/chat-reply-language.spec.tsx b/web/tests/chat-reply-language.spec.tsx
new file mode 100644
index 000000000..84ecd10fa
--- /dev/null
+++ b/web/tests/chat-reply-language.spec.tsx
@@ -0,0 +1,114 @@
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+ RESPONSE_LANGUAGE_EVENT,
+ RESPONSE_LANGUAGE_STORAGE_KEY,
+} from "@/context/app-shell-storage";
+import {
+ ChatStateAdapterProvider,
+ useChatStateAdapter,
+} from "@/features/chat/ChatStateAdapter";
+
+const mocks = vi.hoisted(() => ({
+ getSession: vi.fn(),
+ updateReplyLanguage: vi.fn(),
+ requests: [] as Record<string, unknown>[],
+}));
+
+vi.mock("@/lib/session-api", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@/lib/session-api")>()),
+ getSession: mocks.getSession,
+ updateSessionReplyLanguage: mocks.updateReplyLanguage,
+}));
+
+vi.mock("@/features/chat/transport/UnifiedTurnClient", () => ({
+ UnifiedTurnClient: class {
+ connected = true;
+ connect() {}
+ disconnect() {}
+ setResumeState() {}
+ send(message: Record<string, unknown>) {
+ mocks.requests.push(message);
+ }
+ },
+}));
+
+const session = (replyLanguageOverride: string | null) => ({
+ id: "session-1",
+ session_id: "session-1",
+ title: "Math",
+ status: "completed",
+ created_at: 1,
+ updated_at: 1,
+ messages: [],
+ preferences: {
+ language: "zh",
+ reply_language_override: replyLanguageOverride,
+ },
+});
+
+function Harness() {
+ const { state, loadSession, setReplyLanguageOverride, sendMessage } = useChatStateAdapter();
+ return (
+ <>
+ <button onClick={() => void loadSession("session-1")}>Load</button>
+ <button onClick={() => void setReplyLanguageOverride("de").catch(() => undefined)}>Fix German</button>
+ <button onClick={() => void setReplyLanguageOverride(null).catch(() => undefined)}>Use account</button>
+ <button onClick={() => sendMessage("Explain this")}>Send</button>
+ <output data-testid="session-language">
+ {state.sessionId ?? "draft"}:{state.replyLanguageOverride ?? "account"}:{state.language}
+ </output>
+ </>
+ );
+}
+
+const starts = () => mocks.requests.filter((request) => request.type === "start_turn");
+
+beforeEach(() => {
+ localStorage.clear();
+ localStorage.setItem(RESPONSE_LANGUAGE_STORAGE_KEY, "zh");
+ mocks.requests.length = 0;
+ mocks.getSession.mockReset().mockResolvedValue(session("fr"));
+ mocks.updateReplyLanguage.mockReset().mockImplementation(async (_id, language) => session(language));
+});
+
+describe("conversation reply language", () => {
+ it("loads a fixed language, ignores account changes, and clears to the current account default", async () => {
+ render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ fireEvent.click(screen.getByText("Load"));
+ await waitFor(() => expect(screen.getByTestId("session-language")).toHaveTextContent("session-1:fr:fr"));
+
+ localStorage.setItem(RESPONSE_LANGUAGE_STORAGE_KEY, "ja");
+ act(() => window.dispatchEvent(new CustomEvent(RESPONSE_LANGUAGE_EVENT, { detail: { language: "ja" } })));
+ expect(screen.getByTestId("session-language")).toHaveTextContent("session-1:fr:fr");
+ fireEvent.click(screen.getByText("Send"));
+ expect(starts()).toHaveLength(1);
+ expect(starts()[0].language).toBe("fr");
+ expect(starts()[0]).not.toHaveProperty("reply_language_override");
+
+ fireEvent.click(screen.getByText("Use account"));
+ await waitFor(() => expect(mocks.updateReplyLanguage).toHaveBeenCalledWith("session-1", null, undefined));
+ await waitFor(() => expect(screen.getByTestId("session-language")).toHaveTextContent("session-1:account:ja"));
+ });
+
+ it("persists a new draft's choice with the first turn", async () => {
+ render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ fireEvent.click(screen.getByText("Fix German"));
+ await waitFor(() => expect(screen.getByTestId("session-language")).toHaveTextContent("draft:de:de"));
+ fireEvent.click(screen.getByText("Send"));
+ expect(starts()).toHaveLength(1);
+ expect(starts()[0]).toMatchObject({ language: "de", reply_language_override: "de" });
+ expect(mocks.updateReplyLanguage).not.toHaveBeenCalled();
+ });
+
+ it("keeps the saved selector when changing an existing conversation fails", async () => {
+ mocks.updateReplyLanguage.mockRejectedValue(new Error("Save failed"));
+ render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ fireEvent.click(screen.getByText("Load"));
+ await waitFor(() => expect(screen.getByTestId("session-language")).toHaveTextContent("session-1:fr:fr"));
+ fireEvent.click(screen.getByText("Fix German"));
+ await waitFor(() => expect(mocks.updateReplyLanguage).toHaveBeenCalled());
+ expect(screen.getByTestId("session-language")).toHaveTextContent("session-1:fr:fr");
+ });
+});
diff --git a/web/tests/reply-language-save.test.ts b/web/tests/reply-language-save.test.ts
new file mode 100644
index 000000000..d35ac81c8
--- /dev/null
+++ b/web/tests/reply-language-save.test.ts
@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { waitForReplyLanguageSave } from "../features/chat/controllers/reply-language-save";
+
+test("a failed selector save keeps the draft and blocks sending in the old language", async () => {
+ const restored: string[] = [];
+ const send = async (pending: Promise<void> | null) => {
+ if (!(await waitForReplyLanguageSave(pending, "Explain in French", (draft) => restored.push(draft)))) {
+ return false;
+ }
+ return true;
+ };
+
+ assert.equal(await send(Promise.reject(new Error("Save failed"))), false);
+ assert.deepEqual(restored, ["Explain in French"]);
+ assert.equal(await send(Promise.resolve()), true);
+ assert.equal(await send(null), true);
+});
diff --git a/web/tests/start-turn-input.test.ts b/web/tests/start-turn-input.test.ts
index 6faaee8b2..8b77bd33b 100644
--- a/web/tests/start-turn-input.test.ts
+++ b/web/tests/start-turn-input.test.ts
@@ -104,6 +104,21 @@ test("optional routing fields preserve omitted versus explicit null", () => {
assert.equal(explicit.capability, null);
});
+test("a draft's reply language selector is explicit and a normal turn preserves the session choice", () => {
+ const normal = buildStartTurnInput({ content: "Continue", sessionId: "session-1", language: "en" });
+ const fixed = buildStartTurnInput({
+ content: "用法语教我数学",
+ language: "zh",
+ replyLanguageOverride: "fr",
+ });
+ const cleared = buildStartTurnInput({ content: "Use default", replyLanguageOverride: null });
+
+ assert.equal("reply_language_override" in normal, false);
+ assert.equal(fixed.reply_language_override, "fr");
+ assert.equal(fixed.language, "zh");
+ assert.equal(cleared.reply_language_override, null);
+});
+
test("the positional compatibility adapter produces object-shaped input", () => {
const input = legacySendMessageInput(
{ content: "legacy", config: { difficulty: "hard" } },