DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Generated behavior slice of the unified turn runtime."""
from __future__ import annotations
import asyncio
import contextlib
import time
from typing import TYPE_CHECKING, Any
import uuid
from deeptutor.core.stream import StreamEvent, StreamEventType
from deeptutor.core.turn_request import TurnRequest
from deeptutor.runtime.capability_routing import route_explicit_quiz_request
from deeptutor.services.session.protocol import (
SUBMISSION_ASSISTANT_FIELD,
SUBMISSION_PREVIOUS_TURN_FIELD,
SUBMISSION_REPLAY_FIELD,
SUBMISSION_USER_FIELD,
)
from deeptutor.services.session.workspace_preferences import (
WORKSPACE_MODE_MASTERY,
WORKSPACE_MODE_READING,
)
from deeptutor.services.workspace.activity import workspace_writer
from .._turn_runtime_shared import (
_coerce_bool,
_extract_side_chat_context,
_llm_selection_dict,
_mastery_loop_managed,
_mastery_path_id,
_note_generation,
_partner_group_references,
_reading_material_id,
_reading_material_revision,
_reading_references,
_reading_workspace_id,
_resolve_side_chat_context,
_timed_media_id,
_TurnExecution,
_workspace_mode,
)
if TYPE_CHECKING:
from deeptutor.runtime.coordination import RuntimeCoordinator
from deeptutor.services.session.protocol import SessionStoreProtocol
# Request snapshots use the browser's display keys. Only these saved turn
# inputs are restored by Resend; runtime bookkeeping and message identity are
# always assembled from the persisted message and current session instead.
_REPLAY_SNAPSHOT_FIELDS: dict[str, str] = {
"capability": "capability",
"tools": "enabledTools",
"knowledge_bases": "knowledgeBases",
"language": "language",
"config": "config",
"notebook_references": "notebookReferences",
"history_references": "historyReferences",
"partner_group_references": "partnerGroupReferences",
"question_notebook_references": "questionNotebookReferences",
"book_references": "bookReferences",
"reading_references": "readingReferences",
"memory_references": "memoryReferences",
"skills": "skills",
"mcp": "mcp",
"persona": "persona",
"llm_selection": "llmSelection",
"workspace_mode": "workspaceMode",
"workspace_id": "workspaceId",
"note_document_id": "noteDocumentId",
"note_generation": "noteGeneration",
"mastery_path_id": "masteryPathId",
"mastery_session_mode": "masterySessionMode",
"mastery_answer": "masteryAnswer",
"mastery_skip": "masterySkip",
"reading_material_id": "readingMaterialId",
"reading_material_revision": "readingMaterialRevision",
"reading_workspace_id": "readingWorkspaceId",
"timed_media_id": "timedMediaId",
"consult_partner_id": "consultPartnerId",
"partner_discussion_group_id": "partnerDiscussionGroupId",
"answer_by": "answerBy",
"auto_route": "autoRoute",
}
def _tutor_thread_preferences(context: dict[str, Any]) -> dict[str, Any]:
if context.get("selected_text"):
return {
"tutor_scope": "selection",
"tutor_selected_text": str(context["selected_text"])[:2000],
"tutor_source_message_id": context.get("source_message_id"),
}
return {"tutor_scope": "conversation"}
class TurnRequestPreparer:
if TYPE_CHECKING:
store: SessionStoreProtocol
coordinator: RuntimeCoordinator | None
owner_id: str
_coordination_scope: str
_lock: asyncio.Lock
_executions: dict[str, _TurnExecution]
async def _ensure_accepting_turns(self) -> None: ...
def _turns_blocked_for_update_locked(self) -> bool: ...
async def _validate_mastery_session_topic(
self,
*,
session_id: str,
requested_path_id: str,
remembered_path_id: str,
) -> None: ...
async def _commit_mastery_card_answer(
self,
*,
path_id: str,
session_id: str,
turn_id: str,
question_id: str,
answer: str,
answers: dict[str, str] | None = None,
) -> None: ...
async def _acquire_mastery_path_lease(
self,
*,
path_id: str,
session_id: str,
turn_id: str,
owns_path: bool,
) -> None: ...
async def _publish_live_event(
self,
execution: _TurnExecution,
event: StreamEvent,
) -> dict[str, Any]: ...
async def _run_turn(self, execution: _TurnExecution) -> None: ...
async def _coordinate_execution(self, execution: _TurnExecution) -> None: ...
@workspace_writer
async def start_turn(
self,
payload: dict[str, Any],
*,
replace_assistant_message_id: int | str | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]:
await self._ensure_accepting_turns()
from deeptutor.services.workspace.context import get_workspace_scope
active_scope = get_workspace_scope()
if active_scope is not None and active_scope.archived:
raise RuntimeError("Restore this workspace before starting a conversation.")
# ``TurnRuntimeManager`` remains a one-version compatibility facade;
# transport adapters normally strip their envelope before reaching it.
payload = TurnRequest.model_validate(
{key: value for key, value in payload.items() if key != "type"}
).to_payload()
persona_explicit = "persona" in payload
if not payload.get("language"):
from deeptutor.services.settings.interface_settings import (
get_response_language,
)
payload = {**payload, "language": get_response_language(default="en")}
raw_config = dict(payload.get("config", {}) or {})
linked_task_ids = raw_config.pop("linked_task_ids", None)
resource_reuse = raw_config.pop("_resource_reuse", None)
persistent_kbs = raw_config.pop("_persistent_knowledge_bases", None)
per_turn_auto_route = payload.get("auto_route")
if per_turn_auto_route is None:
from deeptutor.services.config.runtime_settings import load_system_settings
routing_enabled = _coerce_bool(
load_system_settings().get("capability_routing_enabled"), False
)
else:
routing_enabled = _coerce_bool(per_turn_auto_route, False)
if (
payload.get("session_id")
and await self.store.get_session(payload["session_id"]) is None
):
raise RuntimeError("Conversation not found in this workspace.")
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.
from deeptutor.core.identities import is_partner_user_id
from deeptutor.multi_user.context import get_current_user
from deeptutor.services.workspace import get_content_workspace_service
from deeptutor.services.workspace.context import get_workspace_scope
scope = get_workspace_scope()
if scope is not None:
requested = str(payload.get("workspace_id") or "")
if "workspace_id" in payload and requested != scope.workspace_id:
raise RuntimeError("The request workspace does not match its connection.")
stored = str(preferences.get("workspace_id") or "")
if "workspace_id" in preferences and stored != scope.workspace_id:
raise RuntimeError("The conversation belongs to another workspace.")
payload["workspace_id"] = scope.workspace_id
content_workspace_id = str(preferences.get("workspace_id") or "").strip()
if "workspace_id" in payload:
requested_workspace_id = str(payload.get("workspace_id") or "").strip()
if "workspace_id" in preferences and requested_workspace_id != content_workspace_id:
raise RuntimeError("The conversation workspace changed. Reload the conversation.")
content_workspace_id = requested_workspace_id
content_workspace_enabled = (
"workspace_id" in preferences
or "workspace_id" in payload
or (not is_partner_user_id(get_current_user().id))
)
if content_workspace_enabled:
workspace_service = get_content_workspace_service()
if content_workspace_id == workspace_service.general_binding().workspace_id:
content_workspace_id = ""
binding = (
workspace_service.validate_chat_binding(
content_workspace_id,
existing=content_workspace_id == preferences.get("workspace_id"),
)
if content_workspace_id
else workspace_service.session_binding(session["id"])
)
payload["_content_workspace_id"] = binding.workspace_id
payload["_workspace_instructions"] = workspace_service.workspace_instructions(
binding.workspace_id
)
legacy_watching = (
payload.get("workspace_mode") == "immersive_watching"
or payload.get("capability") == "immersive_watching"
or payload.get("session_kind") == "immersive_watching"
or preferences.get("workspace_mode") == "immersive_watching"
or preferences.get("capability") == "immersive_watching"
or preferences.get("session_kind") == "immersive_watching"
)
if legacy_watching:
timed_media_id = _timed_media_id(
payload.get("timed_media_id") or preferences.get("timed_media_id")
)
if not timed_media_id:
raise RuntimeError("The legacy Watching video is unavailable.")
try:
from deeptutor.video_learning.reading_migration import WatchingToReadingMigration
migrated = await WatchingToReadingMigration().migrate(
timed_media_id,
session_id=str(session.get("id") or ""),
session_title=str(session.get("title") or "Imported video conversation"),
)
except Exception as exc:
raise RuntimeError(
"The legacy Watching video could not be opened in Reading."
) from exc
preferences = {
**preferences,
"capability": "chat",
"workspace_mode": WORKSPACE_MODE_READING,
"session_kind": "immersive_reading",
"reading_workspace_id": migrated.reading_workspace_id,
"reading_material_id": migrated.reading_material_id,
"timed_media_id": timed_media_id,
}
legacy_viewport = (
payload.get("timed_media_viewport") or preferences.get("timed_media_viewport") or {}
)
preferences.pop("timed_media_viewport", None)
session["preferences"] = preferences
await self.store.update_session_preferences(str(session.get("id")), preferences)
payload = {
**payload,
"capability": "chat",
"workspace_mode": WORKSPACE_MODE_READING,
"reading_workspace_id": migrated.reading_workspace_id,
"reading_material_id": migrated.reading_material_id,
"timed_media_id": timed_media_id,
}
# TimedMedia remains a legacy cache pointer on the session, but
# execution is wholly Reading-owned from here onward.
if (
isinstance(legacy_viewport, dict)
and legacy_viewport.get("time_seconds") is not None
):
payload["reading_viewport"] = {"time_seconds": legacy_viewport["time_seconds"]}
payload.pop("timed_media_id", None)
payload.pop("timed_media_viewport", None)
requested_capability = str(payload.get("capability") or "chat")
# Resolved before routing, and from the *requested* action: the
# workspace is what decides whether this turn may be re-routed at all,
# so it cannot be derived from the routing outcome.
workspace_mode_explicit = "workspace_mode" in payload
workspace_mode = _workspace_mode(
payload.get("workspace_mode")
if workspace_mode_explicit
else preferences.get("workspace_mode"),
capability=requested_capability,
)
capability_route = route_explicit_quiz_request(
payload.get("content"),
requested_capability,
enabled=routing_enabled,
workspace_mode=workspace_mode,
)
capability = (
capability_route.capability if capability_route is not None else requested_capability
)
try:
from deeptutor.multi_user.learning_access import apply_learning_policy
payload = apply_learning_policy({**payload, "capability": capability})
except PermissionError as exc:
raise RuntimeError(str(exc)) from exc
payload.pop("timed_media_id", None)
payload.pop("timed_media_viewport", None)
try:
from deeptutor.runtime.request_contracts import validate_capability_config
# A routed capability owns a different schema. Chat-only options
# must not be smuggled into the generator; the user request itself
# carries the desired topic/count.
validated_public_config = validate_capability_config(
capability,
{} if capability_route is not None else raw_config,
)
except ValueError as exc:
raise RuntimeError(str(exc)) from exc
payload = {
**payload,
"capability": capability,
"workspace_mode": workspace_mode,
"requested_capability": requested_capability,
"capability_route": (
capability_route.as_metadata() if capability_route is not None else None
),
"config": validated_public_config,
}
reading_workspace_id = _reading_workspace_id(payload.get("reading_workspace_id"))
reading_material_id = _reading_material_id(payload.get("reading_material_id"))
reading_material_revision = _reading_material_revision(
payload.get("reading_material_revision")
)
reading_catalog = None
if workspace_mode == WORKSPACE_MODE_READING and reading_workspace_id:
from deeptutor.reading import ReadingCatalogStore
reading_catalog = ReadingCatalogStore()
reading_workspace = reading_catalog.get_workspace(reading_workspace_id)
if reading_workspace is None:
raise RuntimeError("The reading workspace is unavailable.")
reading_material_id = reading_material_id or str(
reading_workspace.active_material_id or ""
)
if reading_material_id and reading_material_id not in {
tab.material.material_id for tab in reading_workspace.tabs
}:
raise RuntimeError("The active material is not part of this reading workspace.")
# The workspace and saved session can still contain a material whose
# learner assignment has since been revoked. Authorize the resolved
# material, including a default chosen from the workspace, before
# attaching the session or admitting a replayed turn.
if reading_material_id:
from deeptutor.multi_user.learning_access import assert_learning_material
try:
assert_learning_material(reading_material_id)
except PermissionError as exc:
raise RuntimeError(str(exc)) from exc
if reading_catalog is not None:
reading_catalog.attach_session(
reading_workspace_id,
session["id"],
title=str(session.get("title") or "New reading conversation"),
active_material_id=reading_material_id or None,
)
payload = {
**payload,
"reading_workspace_id": reading_workspace_id,
"reading_material_id": reading_material_id,
"reading_material_revision": reading_material_revision,
}
# A mastery path has a longer lifetime than any one conversation.
# Persist the explicit association on the session, and restore it on
# later turns whose frontend payload omits the field.
mastery_path_explicit = "mastery_path_id" in payload
configured_mastery_path_id = _mastery_path_id(
payload.get("mastery_path_id")
if mastery_path_explicit
else preferences.get("mastery_path_id")
)
mastery_binding = None
if workspace_mode == WORKSPACE_MODE_MASTERY:
from deeptutor.learning.identity import resolve_mastery_path_binding
mastery_binding = resolve_mastery_path_binding(
configured_path_id=configured_mastery_path_id,
book_references=payload.get("book_references", []),
session_id=session["id"],
)
mastery_path_id = mastery_binding.path_id
await self._validate_mastery_session_topic(
session_id=session["id"],
requested_path_id=mastery_path_id,
remembered_path_id=_mastery_path_id(preferences.get("mastery_path_id")),
)
else:
mastery_path_id = configured_mastery_path_id
mastery_lease_managed = bool(
mastery_binding is not None and _mastery_loop_managed(workspace_mode, capability)
)
# What this conversation is for — designing the outline, learning, or
# reviewing. Durable session state like the path id, but *mutable*:
# the tutor may change it mid-turn with ``mastery_mode`` and the
# learner may change it from the header, so the value a turn starts
# with is only where it starts.
# ``or``, not "is the key present": the client writes this key on every
# turn and leaves it null whenever it does not happen to hold the mode
# in memory (a reload, a session loaded from the server before its
# preference came back). Reading a null as "the client said none" threw
# away the mode the conversation was actually in — so the tutor was
# told it was studying while the learner watched the outline mode
# highlighted above the transcript, and never switched because it
# believed it already had.
raw_mastery_mode = payload.get("mastery_session_mode") or preferences.get(
"mastery_session_mode"
)
# ``enforced_mode`` rather than ``normalize_mode``: a conversation that
# never recorded a mode must stay unrecorded all the way down to the
# tools, which read the absence as "enforce nothing".
mastery_session_mode = None
if raw_mastery_mode:
from deeptutor.modules.catalog import require_module
require_module("mastery")
from deeptutor.capabilities.mastery.mode import enforced_mode
mastery_session_mode = enforced_mode(raw_mastery_mode)
payload = {
**payload,
"mastery_path_id": mastery_path_id,
"mastery_path_lease_managed": mastery_lease_managed,
"mastery_session_mode": mastery_session_mode,
}
# Persona is a session-level preference (mirrors llm_selection): an
# explicit ``persona`` key in the payload — including an empty string,
# which means "Default" / no persona — wins and is persisted below.
# A course default is filled above only when that key was absent; with
# neither, the session's stored preference survives reloads.
persona_pref = str(
(payload.get("persona") if "persona" in payload else preferences.get("persona")) or ""
).strip()
payload = {**payload, "persona": persona_pref}
# Which skills and MCP servers this conversation narrowed itself to,
# resolved the same way as persona and the KB scope: an explicit key in
# the payload wins and is persisted below (an explicit empty list means
# "back to everything the workspace allows"), an absent key keeps what
# the conversation already chose so a reload does not widen its reach.
skills_explicit = "skills" in payload
mcp_explicit = "mcp" in payload
selected_skills = list(
(payload.get("skills") if skills_explicit else preferences.get("skills")) or []
)
selected_mcp = list((payload.get("mcp") if mcp_explicit else preferences.get("mcp")) or [])
payload = {**payload, "skills": selected_skills, "mcp": selected_mcp}
raw_llm_selection = payload.get("llm_selection")
if raw_llm_selection is None:
raw_llm_selection = preferences.get("llm_selection")
try:
llm_selection = _llm_selection_dict(raw_llm_selection)
except ValueError as exc:
raise RuntimeError(str(exc)) from exc
if llm_selection:
try:
from deeptutor.multi_user.model_access import apply_allowed_llm_selection
llm_selection = apply_allowed_llm_selection(llm_selection) or {}
except PermissionError as exc:
raise RuntimeError(str(exc)) from exc
else:
# Non-admin users MUST end up with a concrete llm_selection so we
# never silently fall through to the global LLM client (which is
# configured from admin runtime settings). Admin keeps the existing behavior
# (None llm_selection → default config from admin scope).
from deeptutor.multi_user.context import get_current_user
from deeptutor.multi_user.model_access import (
has_capability_access,
redacted_model_access,
)
current_user = get_current_user()
if not current_user.is_admin:
# Single gate, shared with the frontend lock and any HTTP
# surface: no usable LLM grant → a clear terminal error here
# instead of a silent fall-through to the global client.
if not has_capability_access("llm"):
raise RuntimeError(
"No LLM model is assigned to your account. Please contact an administrator."
)
# Pin the first granted-and-available model as the selection.
assigned_llms = [
item
for item in redacted_model_access(current_user.id).get("llm", [])
if item.get("available")
]
llm_selection = {
"profile_id": assigned_llms[0].get("profile_id"),
"model_id": assigned_llms[0].get("model_id"),
}
if llm_selection:
from deeptutor.multi_user.personal_models import merge_personal_llm_profiles
from deeptutor.services.config import get_model_catalog_service
from deeptutor.services.model_selection import (
LLMSelection,
apply_llm_selection_to_catalog,
)
try:
# Personal (owner-bound) profiles live in the user's own
# catalog, so validating against the shared one alone would
# reject a Codex model the user signed in for themselves —
# the same merge the resolution path performs (#781).
apply_llm_selection_to_catalog(
merge_personal_llm_profiles(get_model_catalog_service().load()),
LLMSelection.from_payload(llm_selection),
)
except ValueError as exc:
raise RuntimeError(str(exc)) from exc
# If the caller didn't pin a per-turn tool list (e.g. non-web
# channels or the new web UI which sources tools from
# /settings/tools), back-fill from the user's saved toggleable-tool
# preference so the chat pipeline sees the same set the user picked
# in Settings. Callers that explicitly pass ``tools`` (including
# an empty list) keep their value untouched.
if payload.get("tools") is None:
try:
from deeptutor.services.settings.interface_settings import (
get_enabled_optional_tools,
)
payload = {**payload, "tools": list(get_enabled_optional_tools())}
except Exception:
payload = {**payload, "tools": []}
# Admin-imposed per-user tool whitelist (grant v2). Sits after the
# back-fill so explicit caller lists and settings defaults pass the
# same gate; this is the single enforcement point for every
# capability's turn.
from deeptutor.multi_user.tool_access import allowed_optional_tools
allowed_tools = allowed_optional_tools()
if allowed_tools is not None:
payload = {
**payload,
"tools": [t for t in (payload.get("tools") or []) if t in allowed_tools],
}
if capability_route is not None and capability_route.auto_routed:
from deeptutor.runtime.registry.capability_registry import (
get_capability_registry,
)
routed_capability = get_capability_registry().get(capability_route.capability)
if routed_capability is not None:
allowed_by_manifest = set(routed_capability.manifest.tools_used)
payload = {
**payload,
"tools": [
tool for tool in (payload.get("tools") or []) if tool in allowed_by_manifest
],
}
payload = {**payload, "llm_selection": llm_selection}
if linked_task_ids is not None:
from deeptutor.services.task_board import LinkTasks, get_task_board_store
from deeptutor.services.workspace.context import current_workspace_id
task_links = LinkTasks(workspace_id=current_workspace_id(), task_ids=linked_task_ids)
await asyncio.to_thread(get_task_board_store().link_tasks, session["id"], task_links)
preference_update: dict[str, Any] = {
# Auto-routing is a one-turn execution choice; keep the durable
# preference on what the caller explicitly selected.
"capability": requested_capability,
"tools": list(payload.get("tools") or []),
"knowledge_bases": list(payload.get("knowledge_bases") or []),
"language": str(payload.get("language") or "en"),
# Who this conversation is handed to; "" when DeepTutor answers.
# The client restates it every turn, so the last one is current.
"answer_by": str(payload.get("answer_by") or ""),
}
if payload.get("capability_once"):
# One turn in another mode; the conversation keeps its own.
preference_update.pop("capability")
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
# preference. Explicit empties still clear a workspace, while a
# non-empty legacy capability is persisted as part of migration.
if workspace_mode_explicit or workspace_mode:
preference_update["workspace_mode"] = workspace_mode
if payload.get("note_document_id"):
preference_update["note_document_id"] = payload["note_document_id"]
raw_selection_context = payload.get("selection_tutor_context")
if isinstance(raw_selection_context, dict):
selection_tutor_context = _extract_side_chat_context(
{"selection_tutor_context": dict(raw_selection_context)}
)
if selection_tutor_context is None:
raise RuntimeError(
"A Little Tutor thread needs selected text or the conversation it is about"
)
try:
resolved_selection_context = await _resolve_side_chat_context(
self.store,
selection_tutor_context,
)
except ValueError as exc:
raise RuntimeError(str(exc)) from exc
# The executor resolves again when the turn runs; a side chat's
# transcript is that resolution's output, not part of the request.
selection_tutor_context = {
key: value
for key, value in resolved_selection_context.items()
if key != "conversation_messages"
}
payload["selection_tutor_context"] = selection_tutor_context
parent_session_id = str(selection_tutor_context.get("parent_session_id") or "").strip()
if parent_session_id == session["id"]:
raise RuntimeError("A selection tutor session cannot parent itself")
if parent_session_id:
from deeptutor.services.session.organization import (
validate_parent_assignment,
)
try:
parent_session = await validate_parent_assignment(
self.store,
session_id=session["id"],
parent_session_id=parent_session_id,
)
except (LookupError, ValueError) as exc:
raise RuntimeError(str(exc)) from exc
parent_preferences = parent_session.get("preferences") or {}
if "workspace_id" in parent_preferences:
inherited_id = str(parent_preferences.get("workspace_id") or "")
preference_update["workspace_id"] = inherited_id or None
workspace_service = get_content_workspace_service()
inherited_binding = (
workspace_service.validate_chat_binding(inherited_id, existing=True)
if inherited_id
else workspace_service.session_binding(parent_session_id)
)
payload["_content_workspace_id"] = inherited_binding.workspace_id
payload["_workspace_instructions"] = workspace_service.workspace_instructions(
inherited_binding.workspace_id
)
preference_update.update(
{
"parent_session_id": parent_session_id,
"session_kind": "selection_tutor",
"side_chat_group_id": str(payload.get("partner_discussion_group_id") or ""),
**_tutor_thread_preferences(selection_tutor_context),
}
)
if llm_selection:
preference_update["llm_selection"] = llm_selection
if persona_explicit:
# Persist explicit set AND explicit clear ("" = back to Default).
preference_update["persona"] = persona_pref
if skills_explicit:
preference_update["skills"] = selected_skills
if mcp_explicit:
preference_update["mcp"] = selected_mcp
from .resource_reuse import apply_resource_reuse
apply_resource_reuse(preference_update, resource_reuse, persistent_kbs)
if mastery_path_explicit or mastery_binding is not None:
# Mastery turns persist their fully resolved path so a later turn
# cannot silently fall back to a different aggregate.
preference_update["mastery_path_id"] = mastery_path_id
# …and what the conversation is for, which is decided when it is
# opened and must survive every later turn that does not restate it.
if mastery_session_mode:
preference_update["mastery_session_mode"] = mastery_session_mode
if workspace_mode == WORKSPACE_MODE_READING and reading_workspace_id:
preference_update.update(
{
"session_kind": "immersive_reading",
"reading_workspace_id": reading_workspace_id,
"reading_material_id": reading_material_id,
}
)
elif (
workspace_mode_explicit
and not workspace_mode
and preferences.get("session_kind") == "immersive_reading"
):
preference_update.update(
{
"session_kind": "chat",
"reading_workspace_id": "",
"reading_material_id": "",
}
)
lease = None
if self.coordinator is not None:
turn_id = f"turn_{int(time.time() * 1000)}_{uuid.uuid4().hex[:10]}"
lease = await self.coordinator.acquire_turn(
turn_id,
f"{self._coordination_scope}:{session['id']}",
self.owner_id,
)
if lease is None:
raise RuntimeError("Session already has an active or recovering turn")
try:
if not payload.get("preserve_session_preferences"):
await self.store.update_session_preferences(session["id"], preference_update)
submission_kwargs = {}
if (
payload.get("client_submission_id")
and payload.get("persist_user_message", True)
and not payload.get("regenerate")
and callable(getattr(self.store, "reserve_submission", None))
):
submission_kwargs["submission_id"] = payload["client_submission_id"]
if lease is None:
turn = await self.store.create_turn(
session["id"], capability=capability, **submission_kwargs
)
else:
turn = await self.store.begin_turn(
session["id"],
capability=capability,
turn_id=lease.turn_id,
owner_id=lease.owner_id,
fencing_token=lease.fencing_token,
**submission_kwargs,
)
except Exception:
if lease is not None and self.coordinator is not None:
with contextlib.suppress(Exception):
await self.coordinator.release_turn(lease)
raise
if turn.pop(SUBMISSION_REPLAY_FIELD, False):
if lease is not None and self.coordinator is not None:
await self.coordinator.release_turn(lease)
return session, turn
user_message_id = turn.pop(SUBMISSION_USER_FIELD, None)
prior_assistant_id = turn.pop(SUBMISSION_ASSISTANT_FIELD, None)
prior_turn_id = turn.pop(SUBMISSION_PREVIOUS_TURN_FIELD, None)
if user_message_id is not None:
payload = {
**payload,
"persist_user_message": False,
"regenerate": True,
"regenerated_from_message_id": user_message_id,
"superseded_turn_id": prior_turn_id,
}
if replace_assistant_message_id is None:
replace_assistant_message_id = prior_assistant_id
execution = _TurnExecution(
turn_id=turn["id"],
session_id=session["id"],
capability=capability,
payload=dict(payload),
lease=lease,
)
# Publish an ownership marker before trying to recover another path
# lease. Two start_turn calls can otherwise interleave after the first
# turn row is created but before its task is registered, causing the
# second caller to misclassify that healthy turn as a restart orphan.
async with self._lock:
update_blocked = self._turns_blocked_for_update_locked()
if not update_blocked:
self._executions[turn["id"]] = execution
if update_blocked:
with contextlib.suppress(Exception):
await self.store.transition_turn(
turn["id"],
"failed",
error="DeepTutor is preparing an update; try again after it reconnects",
failure_code="rejected",
)
raise RuntimeError("DeepTutor is preparing an update; try again after it reconnects")
mastery_lease_acquired = False
if mastery_binding is not None and mastery_lease_managed:
try:
await self._acquire_mastery_path_lease(
path_id=mastery_binding.path_id,
session_id=session["id"],
turn_id=turn["id"],
owns_path=mastery_binding.owned_by_session,
)
mastery_lease_acquired = True
card_answer = payload.get("mastery_answer") or {}
if isinstance(card_answer, dict) and card_answer.get("question_id"):
# Commit before the loop starts so the tutor's first
# mastery_status already reports this answer.
await self._commit_mastery_card_answer(
path_id=mastery_binding.path_id,
session_id=session["id"],
turn_id=turn["id"],
question_id=str(card_answer.get("question_id") or ""),
answer=str(card_answer.get("text") or ""),
**(
{"answers": card_answer["answers"]}
if card_answer.get("answers") is not None
else {}
),
)
except Exception as exc:
async with self._lock:
self._executions.pop(turn["id"], None)
with contextlib.suppress(Exception):
await self.store.transition_turn(
turn["id"],
"failed",
error=str(exc),
failure_code="rejected",
)
raise
persisted_turn = await self.store.get_turn(turn["id"])
if persisted_turn is None or persisted_turn.get("status") != "running":
# An administrative reset/delete can cancel the placeholder
# while lease acquisition is in flight. Never launch a task
# after that cancellation has already become durable.
from deeptutor.learning.storage import LearningStore
async with self._lock:
self._executions.pop(turn["id"], None)
with contextlib.suppress(Exception):
await asyncio.to_thread(
LearningStore().release_path_lease,
mastery_binding.path_id,
turn_id=turn["id"],
)
raise RuntimeError("Mastery turn was cancelled while starting")
session_metadata: dict[str, Any] = {
"session_id": session["id"],
"turn_id": turn["id"],
}
regenerated_from = payload.get("regenerated_from_message_id")
if regenerated_from is not None:
session_metadata["regenerated_from_message_id"] = regenerated_from
superseded_turn_id = payload.get("superseded_turn_id")
if superseded_turn_id:
session_metadata["superseded_turn_id"] = str(superseded_turn_id)
if payload.get("regenerate"):
session_metadata["regenerate"] = True
if capability_route is not None:
session_metadata["capability_route"] = capability_route.as_metadata()
try:
await self._publish_live_event(
execution,
StreamEvent(
type=StreamEventType.SESSION,
source="turn_runtime",
metadata=session_metadata,
),
)
# Regenerate must remove the old answer before the new task reads
# conversation history. Do it only after the new turn has passed
# admission (including workspace, capability, and model access),
# while no execution task has been scheduled yet. A rejected replay
# must leave the original assistant row and its id intact.
if replace_assistant_message_id is not None:
if not await self.store.delete_message(replace_assistant_message_id):
raise RuntimeError("Unable to replace the previous assistant message")
async with self._lock:
from deeptutor.services.workspace.activity import acquire_activity
activity = acquire_activity()
try:
execution.task = asyncio.create_task(self._run_turn(execution))
except BaseException:
activity.close()
raise
execution.task.add_done_callback(lambda _done: activity.close())
if execution.lease is not None and self.coordinator is not None:
execution.coordination_task = asyncio.create_task(
self._coordinate_execution(execution)
)
except Exception as exc:
async with self._lock:
self._executions.pop(turn["id"], None)
if mastery_binding is not None and mastery_lease_acquired:
from deeptutor.learning.storage import LearningStore
with contextlib.suppress(Exception):
await asyncio.to_thread(
LearningStore().release_path_lease,
mastery_binding.path_id,
turn_id=turn["id"],
)
with contextlib.suppress(Exception):
await self.store.update_turn_status(turn["id"], "failed", str(exc))
if lease is not None and self.coordinator is not None:
with contextlib.suppress(Exception):
await self.coordinator.release_turn(lease)
raise
return session, turn
async def regenerate_last_turn(
self,
session_id: str,
overrides: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]:
"""Re-run the prior user message in ``session_id``.
Deletes the trailing assistant message (if any), then dispatches a new
turn with ``persist_user_message=False`` and ``regenerate=True`` so
the runtime knows not to duplicate the user row or refresh long-term
memory a second time. The original user message stays in place.
``overrides.replay_snapshot`` opts into restoring the saved per-turn
request for a persisted failed-turn Resend. Without it, Regenerate
retains its session-preference behavior. Explicit overrides win over
saved fields, including empty lists and strings.
"""
session_id = str(session_id or "").strip()
if not session_id:
raise RuntimeError("nothing_to_regenerate")
session = await self.store.get_session(session_id)
if session is None:
raise RuntimeError("nothing_to_regenerate")
active = await self.store.get_active_turn(session_id)
if active is not None:
raise RuntimeError("regenerate_busy")
last_user = await self.store.get_last_message(session_id, role="user")
if last_user is None:
raise RuntimeError("nothing_to_regenerate")
last_message = await self.store.get_last_message(session_id)
previous_turn_id: str | None = None
if last_message is not None and last_message.get("role") == "assistant":
for event in last_message.get("events") or []:
turn_id = str((event or {}).get("turn_id") or "")
if turn_id:
previous_turn_id = turn_id
break
preferences = session.get("preferences") or {}
overrides = dict(overrides or {})
replay_snapshot = overrides.pop("replay_snapshot", False) is True
snapshot = {}
metadata = last_user.get("metadata") or {}
if isinstance(metadata, dict):
candidate = metadata.get("request_snapshot") or metadata.get("requestSnapshot")
if isinstance(candidate, dict):
snapshot = candidate
capability = str(
overrides.get("capability")
or last_user.get("capability")
or preferences.get("capability")
or "chat"
)
tools = list(
overrides.get("tools")
if overrides.get("tools") is not None
else preferences.get("tools") or []
)
knowledge_bases = list(
overrides.get("knowledge_bases")
if overrides.get("knowledge_bases") is not None
else preferences.get("knowledge_bases") or []
)
skills = list(
overrides.get("skills")
if overrides.get("skills") is not None
else preferences.get("skills") or []
)
mcp = list(
overrides.get("mcp")
if overrides.get("mcp") is not None
else preferences.get("mcp") or []
)
language = str(overrides.get("language") or preferences.get("language") or "en")
config: dict[str, Any] = dict(overrides.get("config") or {})
consultation_fields = {}
snapshot_config = snapshot.get("config") or {}
for field, snapshot_key in (
("consult_partner_id", "consultPartnerId"),
("partner_discussion_group_id", "partnerDiscussionGroupId"),
("answer_by", "answerBy"),
):
consultation_fields[field] = (
overrides[field]
if field in overrides
else config.get(field, snapshot.get(snapshot_key, snapshot_config.get(field)))
)
llm_selection = (
overrides.get("llm_selection")
if overrides.get("llm_selection") is not None
else snapshot.get("llmSelection") or preferences.get("llm_selection")
)
mastery_path_id = _mastery_path_id(
overrides.get("mastery_path_id")
if "mastery_path_id" in overrides
else snapshot.get("masteryPathId") or preferences.get("mastery_path_id")
)
workspace_mode = _workspace_mode(
overrides.get("workspace_mode")
if "workspace_mode" in overrides
else snapshot.get("workspaceMode") or preferences.get("workspace_mode"),
capability=capability,
)
payload: dict[str, Any] = {
"session_id": session_id,
"capability": capability,
# A turn asked in another mode once (a reading "Quiz me") is
# regenerated in it once, too — not adopted as the chat's mode.
"capability_once": "capability" not in overrides
and snapshot.get("capabilityOnce") is True,
"workspace_mode": workspace_mode,
"content": str(last_user.get("content", "") or ""),
"tools": tools,
"knowledge_bases": knowledge_bases,
"skills": skills,
"mcp": mcp,
"language": language,
"attachments": [
{
key: att.get(key)
for key in ("type", "url", "base64", "filename", "mime_type", "id")
if isinstance(att, dict) and key in att
}
for att in (last_user.get("attachments") or [])
if isinstance(att, dict)
],
# The persisted message-row attachments carry upload-time extras
# (``id``, ``extracted_text``, ``extracted_chars``) that the wire
# contract ``OutgoingAttachment`` forbids; project to the allowed
# fields so start_turn's TurnRequest validation passes on retry
# (#1484 — otherwise the WS closed with no terminal event and the
# UI hung on "Thinking..." forever).
"notebook_references": list(
overrides.get("notebook_references")
if overrides.get("notebook_references") is not None
else preferences.get("notebook_references") or []
),
"history_references": list(
overrides.get("history_references")
if overrides.get("history_references") is not None
else preferences.get("history_references") or []
),
"partner_group_references": _partner_group_references(
overrides.get("partner_group_references")
if overrides.get("partner_group_references") is not None
else snapshot.get("partnerGroupReferences")
or preferences.get("partner_group_references")
or []
),
"book_references": list(
overrides.get("book_references")
if overrides.get("book_references") is not None
else snapshot.get("bookReferences") or []
),
"reading_references": _reading_references(
overrides.get("reading_references")
if "reading_references" in overrides
else snapshot.get("readingReferences")
),
"mastery_path_id": mastery_path_id,
# A regenerate must run as the same kind of conversation the turn
# originally ran as, or it would be handed a different tool surface
# than the answer it is replacing.
"mastery_session_mode": (
overrides.get("mastery_session_mode")
if "mastery_session_mode" in overrides
else preferences.get("mastery_session_mode")
),
# Recovered from the original turn's snapshot so the regenerate runs
# against the same document. An explicit override wins (the reader
# may have moved on), and the viewport is deliberately not restored —
# "where the user was looking" is stale by definition on a retry.
"note_document_id": (
overrides.get("note_document_id")
if "note_document_id" in overrides
else snapshot.get("noteDocumentId") or preferences.get("note_document_id")
)
or None,
"note_generation": _note_generation(
overrides.get("note_generation")
if "note_generation" in overrides
else snapshot.get("noteGeneration")
),
"reading_material_id": _reading_material_id(
overrides.get("reading_material_id")
if "reading_material_id" in overrides
else snapshot.get("readingMaterialId")
),
"reading_material_revision": _reading_material_revision(
overrides.get("reading_material_revision")
if "reading_material_revision" in overrides
else snapshot.get("readingMaterialRevision")
),
"reading_workspace_id": _reading_workspace_id(
overrides.get("reading_workspace_id")
if "reading_workspace_id" in overrides
else snapshot.get("readingWorkspaceId") or preferences.get("reading_workspace_id")
),
"timed_media_id": _timed_media_id(
overrides.get("timed_media_id")
if "timed_media_id" in overrides
else snapshot.get("timedMediaId")
),
"config": config,
**consultation_fields,
"persist_user_message": False,
"regenerate": True,
"regenerated_from_message_id": last_user["id"],
}
if previous_turn_id:
payload["superseded_turn_id"] = previous_turn_id
if llm_selection:
payload["llm_selection"] = llm_selection
if replay_snapshot:
payload["preserve_session_preferences"] = True
# The ordinary Regenerate path intentionally uses current session
# preferences for many fields. Resend instead repeats the failed
# message's saved request. Keys absent from an older snapshot keep
# the legacy fallback, while explicit overrides always take
# precedence, even when they clear a field.
for field, snapshot_key in _REPLAY_SNAPSHOT_FIELDS.items():
if field in overrides:
payload[field] = overrides[field]
elif snapshot_key in snapshot:
payload[field] = snapshot[snapshot_key]
# Validate the complete replay request before removing the answer it
# supersedes. A malformed stored snapshot or override must leave the
# visible conversation intact so the learner can retry safely.
TurnRequest.model_validate(payload)
replace_assistant_message_id = (
last_message["id"]
if last_message is not None and last_message.get("role") == "assistant"
else None
)
if replace_assistant_message_id is None:
return await self.start_turn(payload)
return await self.start_turn(
payload, replace_assistant_message_id=replace_assistant_message_id
)