DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
from __future__ import annotations
import asyncio
import threading
from types import SimpleNamespace
import pytest
from deeptutor.core.stream import StreamEvent, StreamEventType
from deeptutor.learning.storage import LearningStore
from deeptutor.services.session._turn_runtime_shared import _resolve_turn_failure_metadata
from deeptutor.services.session.sqlite_store import SQLiteSessionStore
from deeptutor.services.session.turn_runtime import (
TurnRuntimeManager,
_resolve_turn_outcome,
_TurnExecution,
)
from deeptutor.services.session.turns import lifecycle as lifecycle_module
def _isolate_learning_store(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
def _init(self, root=None):
self._root = tmp_path / "learning"
self._root.mkdir(parents=True, exist_ok=True)
monkeypatch.setattr(LearningStore, "__init__", _init)
def _mastery_payload(session_id: str, path_id: str) -> dict:
return {
"type": "start_turn",
"session_id": session_id,
"capability": "mastery_path",
"mastery_path_id": path_id,
"content": "continue",
"tools": [],
"knowledge_bases": [],
"attachments": [],
"language": "en",
"config": {},
}
def _mastery_chat_payload(session_id: str, path_id: str) -> dict:
return {
**_mastery_payload(session_id, path_id),
"capability": "chat",
"workspace_mode": "mastery_path",
}
def test_terminal_error_marks_turn_failed() -> None:
error_message = "provider authentication failed"
status, error = _resolve_turn_outcome(
[
{
"type": "error",
"content": error_message,
"metadata": {"turn_terminal": True, "status": "failed"},
}
],
StreamEvent(
type=StreamEventType.DONE,
source="chat",
metadata={"status": "failed"},
),
)
assert status == "failed"
assert error == error_message
def test_non_terminal_error_keeps_completed_done_status() -> None:
status, error = _resolve_turn_outcome(
[
{
"type": "error",
"content": "recoverable tool error",
"metadata": {},
}
],
StreamEvent(
type=StreamEventType.DONE,
source="chat",
metadata={"status": "completed"},
),
)
assert status == "completed"
assert error == ""
def test_terminal_error_metadata_resolves_retry_contract() -> None:
code, retryable = _resolve_turn_failure_metadata(
[
{
"type": "error",
"content": "The model exhausted its output budget.",
"metadata": {
"turn_terminal": True,
"error_code": "reasoning_budget_exhausted",
"retryable": True,
},
}
]
)
assert code == "reasoning_budget_exhausted"
assert retryable is True
@pytest.mark.asyncio
async def test_has_live_executions_counts_placeholders_and_running_tasks(tmp_path) -> None:
runtime = TurnRuntimeManager(SQLiteSessionStore(tmp_path / "chat_history.db"))
runtime._executions["placeholder"] = SimpleNamespace(task=None) # type: ignore[assignment]
assert await runtime.has_live_executions() is True
runtime._executions.clear()
task = asyncio.create_task(asyncio.sleep(0))
runtime._executions["running"] = SimpleNamespace(task=task) # type: ignore[assignment]
assert await runtime.has_live_executions() is True
await task
assert await runtime.has_live_executions() is False
@pytest.mark.asyncio
async def test_managed_update_reservation_is_atomic_with_turn_ownership(tmp_path) -> None:
runtime = TurnRuntimeManager(SQLiteSessionStore(tmp_path / "chat_history.db"))
reserved = object()
assert await runtime.reserve_managed_update(lambda: reserved) is reserved
runtime._managed_update_is_active = lambda: True # type: ignore[method-assign]
with pytest.raises(RuntimeError, match="preparing an update"):
await runtime._ensure_accepting_turns()
runtime._managed_update_is_active = lambda: False # type: ignore[method-assign]
await runtime._ensure_accepting_turns()
@pytest.mark.asyncio
async def test_subscribe_turn_does_not_synthesize_done_for_running_turn(tmp_path) -> None:
"""A paused/replaced subscription must not make the UI think the turn ended."""
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
turn = await store.create_turn(session["id"], capability="chat")
execution = _TurnExecution(
turn_id=turn["id"],
session_id=session["id"],
capability="chat",
payload={},
)
runtime._executions[turn["id"]] = execution
events: list[dict] = []
async def _collect() -> None:
async for event in runtime.subscribe_turn(turn["id"], after_seq=0):
events.append(event)
task = asyncio.create_task(_collect())
for _ in range(200):
if execution.subscribers:
break
await asyncio.sleep(0.01)
assert execution.subscribers
await execution.subscribers[0].queue.put(None)
await asyncio.wait_for(task, timeout=1)
assert events == []
persisted = await store.get_turn(turn["id"])
assert persisted is not None
assert persisted["status"] == "running"
@pytest.mark.asyncio
async def test_replacing_subscription_does_not_synthesize_duplicate_done(tmp_path) -> None:
"""Cancelling an old replay subscription must leave termination to its replacement."""
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
turn = await store.create_turn(session["id"], capability="chat")
execution = _TurnExecution(
turn_id=turn["id"],
session_id=session["id"],
capability="chat",
payload={},
)
runtime._executions[turn["id"]] = execution
events: list[dict] = []
async def _collect() -> None:
async for event in runtime.subscribe_turn(turn["id"], after_seq=0):
events.append(event)
task = asyncio.create_task(_collect())
for _ in range(200):
if execution.subscribers:
break
await asyncio.sleep(0.01)
assert execution.subscribers
assert await store.update_turn_status(turn["id"], "completed") is True
task.cancel()
with pytest.raises(asyncio.CancelledError):
await task
assert events == []
@pytest.mark.asyncio
async def test_subscribe_turn_does_not_mutate_remote_running_turn(tmp_path, monkeypatch) -> None:
"""A subscriber may be on a different worker from the turn owner."""
monkeypatch.setattr(lifecycle_module, "_SUBSCRIPTION_POLL_SECONDS", 0.01)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
turn = await store.create_turn(session["id"], capability="chat")
events: list[dict] = []
async def _collect() -> None:
async for event in runtime.subscribe_turn(turn["id"], after_seq=0):
events.append(event)
task = asyncio.create_task(_collect())
await asyncio.sleep(0.04)
persisted = await store.get_turn(turn["id"])
assert persisted is not None
assert persisted["status"] == "running"
assert persisted["error"] == ""
assert events == []
assert await store.update_turn_status(turn["id"], "completed") is True
await asyncio.wait_for(task, timeout=1)
assert [event["type"] for event in events] == ["done"]
@pytest.mark.asyncio
async def test_worker_lost_unblocks_a_stale_local_subscriber(tmp_path, monkeypatch) -> None:
"""Recovery's durable terminal state reaches an abandoned live queue."""
monkeypatch.setattr(lifecycle_module, "_SUBSCRIPTION_POLL_SECONDS", 0.01)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
turn = await store.create_turn(session["id"], capability="mastery_path")
execution = _TurnExecution(
turn_id=turn["id"], session_id=session["id"], capability="mastery_path", payload={}
)
runtime._executions[turn["id"]] = execution
events: list[dict] = []
async def _collect() -> None:
async for event in runtime.subscribe_turn(turn["id"]):
events.append(event)
task = asyncio.create_task(_collect())
for _ in range(100):
if execution.subscribers:
break
await asyncio.sleep(0.01)
assert execution.subscribers
assert await store.transition_turn(
turn["id"], "failed", error="Worker lost", failure_code="worker_lost", retryable=True
)
await asyncio.wait_for(task, timeout=1)
assert [event["type"] for event in events] == ["error", "done"]
assert events[0]["metadata"]["error_code"] == "worker_lost"
assert events[1]["metadata"]["status"] == "failed"
@pytest.mark.asyncio
async def test_subscribe_terminal_turn_synthesizes_protocol_valid_done(tmp_path) -> None:
"""A recovered terminal turn must emit a consumable monotonic DONE."""
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
turn = await store.create_turn(session["id"], capability="chat")
assert await store.update_turn_status(turn["id"], "completed") is True
events = [event async for event in runtime.subscribe_turn(turn["id"], after_seq=0)]
assert len(events) == 1
done = events[0]
assert done["type"] == "done"
assert done["turn_id"] == turn["id"]
assert done["session_id"] == session["id"]
assert done["seq"] == 1
assert isinstance(done["timestamp"], float)
assert done["metadata"] == {"status": "completed", "synthesized": True}
@pytest.mark.asyncio
async def test_subscribe_failed_turn_synthesizes_ordered_error_and_done(tmp_path) -> None:
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
turn = await store.create_turn(session["id"], capability="chat")
assert (
await store.transition_turn(
turn["id"],
"failed",
error="provider failed",
failure_code="reasoning_budget_exhausted",
retryable=True,
)
is True
)
events = [event async for event in runtime.subscribe_turn(turn["id"], after_seq=0)]
assert [event["type"] for event in events] == ["error", "done"]
assert [event["seq"] for event in events] == [1, 2]
assert events[0]["metadata"]["turn_terminal"] is True
assert events[0]["metadata"]["error_code"] == "reasoning_budget_exhausted"
assert events[0]["metadata"]["retryable"] is True
assert events[1]["metadata"]["status"] == "failed"
assert events[1]["metadata"]["error_code"] == "reasoning_budget_exhausted"
assert events[1]["metadata"]["retryable"] is True
@pytest.mark.asyncio
async def test_close_cancels_local_turns_and_wakes_subscribers(tmp_path) -> None:
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
turn = await store.create_turn(session["id"], capability="chat")
execution = _TurnExecution(
turn_id=turn["id"],
session_id=session["id"],
capability="chat",
payload={},
)
execution.task = asyncio.create_task(asyncio.Event().wait())
runtime._executions[turn["id"]] = execution
collected: list[dict] = []
async def _collect() -> None:
async for event in runtime.subscribe_turn(turn["id"]):
collected.append(event)
subscriber_task = asyncio.create_task(_collect())
for _ in range(100):
if execution.subscribers:
break
await asyncio.sleep(0.01)
await runtime.close()
await asyncio.wait_for(subscriber_task, timeout=1)
assert execution.task.cancelled()
assert collected == []
assert await runtime.has_live_executions() is False
@pytest.mark.asyncio
async def test_start_turn_does_not_mutate_apparently_orphaned_turn(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""Only the recovery service may resolve a persisted active turn."""
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session(None)
stale = await store.create_turn(session["id"], capability="chat")
async def _noop_run_turn(_execution):
return None
monkeypatch.setattr(runtime, "_run_turn", _noop_run_turn)
with pytest.raises(RuntimeError, match="active turn"):
await runtime.start_turn(
{
"type": "start_turn",
"session_id": session["id"],
"capability": "chat",
"content": "hello",
"tools": [],
"knowledge_bases": [],
"attachments": [],
"language": "en",
"config": {},
}
)
persisted = await store.get_turn(stale["id"])
assert persisted is not None
assert persisted["status"] == "running"
@pytest.mark.asyncio
async def test_start_turn_preserves_selection_tutor_runtime_context(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""Selected text must survive public config validation into turn execution."""
store = SQLiteSessionStore(tmp_path / "selection-tutor.db")
runtime = TurnRuntimeManager(store)
async def _noop_run_turn(_execution):
return None
monkeypatch.setattr(runtime, "_run_turn", _noop_run_turn)
parent = await store.ensure_session(None)
source_text = "系统会把代码和静态数据加载进内存。"
source_message_id = await store.add_message(
parent["id"],
"assistant",
source_text,
)
selected_context = {
"selected_text": "把代码和静态数据加载进内存",
"parent_session_id": parent["id"],
"source_message_id": source_message_id,
"source_message_text": "untrusted client fallback",
}
_, turn = await runtime.start_turn(
{
"type": "start_turn",
"session_id": None,
"capability": "chat",
"content": "内存不会爆炸吗?",
"tools": [],
"knowledge_bases": [],
"attachments": [],
"language": "zh",
"config": {"selection_tutor_context": selected_context},
}
)
execution = runtime._executions[turn["id"]]
resolved = execution.payload["selection_tutor_context"]
assert resolved["selected_text"] == selected_context["selected_text"]
assert resolved["source_message_text"] == source_text
@pytest.mark.asyncio
async def test_side_chat_starts_from_the_parent_alone(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
store = SQLiteSessionStore(tmp_path / "side-chat.db")
runtime = TurnRuntimeManager(store)
parent = await store.ensure_session(None)
await store.add_message(parent["id"], "user", "Explain fork()")
leaf = await store.add_message(parent["id"], "assistant", "It returns twice.")
async def _noop_run_turn(_execution):
return None
monkeypatch.setattr(runtime, "_run_turn", _noop_run_turn)
child, turn = await runtime.start_turn(
{
"type": "start_turn",
"session_id": None,
"capability": "chat",
"content": "Why twice?",
"tools": [],
"knowledge_bases": [],
"attachments": [],
"language": "en",
"config": {
"selection_tutor_context": {
"scope": "conversation",
"parent_session_id": parent["id"],
"source_message_id": leaf,
}
},
}
)
persisted = await store.get_session(child["id"])
assert persisted is not None
assert persisted["preferences"]["parent_session_id"] == parent["id"]
assert persisted["preferences"]["session_kind"] == "selection_tutor"
assert persisted["preferences"]["tutor_scope"] == "conversation"
# The transcript is resolved again when the turn runs, never queued with it.
queued = runtime._executions[turn["id"]].payload["selection_tutor_context"]
assert "conversation_messages" not in queued
@pytest.mark.asyncio
async def test_reconnect_after_turn_completion_still_carries_message_ids(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""A client that (re)subscribes after the turn already finished and its
in-process execution was cleaned up must still get the persisted-id
metadata on DONE, not just the bare status.
This is the ``resume_from`` path: the WS drops mid-turn (network blip,
backgrounded tab) and reconnects after the turn has already completed
server-side. Without persisted ids on DONE, the reconnecting client can
never run its optimistic-id reconcile swap for that turn -- the
assistant reply stays a real, correctly-persisted row, but the client's
local tree treats it as unreachable until a full session reload.
"""
store = SQLiteSessionStore(tmp_path / "reconnect.db")
runtime = TurnRuntimeManager(store)
class FakeContextBuilder:
def __init__(self, *_args, **_kwargs) -> None:
pass
async def build(self, **_kwargs):
return SimpleNamespace(
conversation_history=[],
conversation_summary="",
context_text="",
token_count=0,
budget=0,
)
class FakeOrchestrator:
async def handle(self, _context):
yield StreamEvent(
type=StreamEventType.CONTENT,
source="chat",
stage="responding",
content="hello there",
metadata={"call_kind": "llm_final_response"},
)
yield StreamEvent(
type=StreamEventType.DONE,
source="chat",
metadata={
"status": "completed",
"usage_summary": {
"total_tokens": 120,
"total_calls": 1,
"cache_hit_rate": 0.75,
"ttft_seconds": 1.5,
},
},
)
async def _noop_title(**_kwargs):
return None
monkeypatch.setattr("deeptutor.services.llm.config.get_llm_config", lambda: SimpleNamespace())
monkeypatch.setattr(
"deeptutor.services.session.context_builder.ContextBuilder",
FakeContextBuilder,
)
monkeypatch.setattr("deeptutor.runtime.orchestrator.ChatOrchestrator", FakeOrchestrator)
monkeypatch.setattr(runtime, "_maybe_generate_session_title", _noop_title)
session, turn = await runtime.start_turn(
{
"type": "start_turn",
"content": "what is 2+2?",
"session_id": None,
"capability": "chat",
"tools": [],
"knowledge_bases": [],
"attachments": [],
"language": "en",
"config": {},
}
)
turn_id = turn["id"]
# No one ever subscribed while the turn ran -- ``_run_turn`` is an
# independent task started inside ``start_turn``, so it runs (and its
# ``finally`` pops ``execution`` from ``_executions``) regardless.
execution = runtime._executions[turn_id]
await execution.task
assert turn_id not in runtime._executions
messages = await store.get_messages(session["id"])
assert [m["role"] for m in messages] == ["user", "assistant"]
real_assistant_id = messages[1]["id"]
saved_usage = next(
e["metadata"]["usage_summary"] for e in messages[1]["events"] if e["type"] == "done"
)
assert saved_usage["total_tokens"] == 120
assert saved_usage["cache_hit_rate"] == 0.75
# The client reconnects now and asks to catch up from the start.
events = [event async for event in runtime.subscribe_turn(turn_id, after_seq=0)]
done_events = [e for e in events if e["type"] == "done"]
assert len(done_events) == 1
assert done_events[0]["metadata"].get("assistant_message_id") == real_assistant_id
assert done_events[0]["metadata"]["usage_summary"] == saved_usage
def _open_mastery_question(path_id: str, *, question_id: str = "q-1"):
"""A built path with one open choice question, answer key ``C``."""
from deeptutor.learning.models import (
KnowledgePoint,
KnowledgeType,
LearningModule,
LearningProgress,
PendingQuestion,
)
from deeptutor.learning.service import LearningService
progress = LearningProgress(
book_id=path_id,
modules=[
LearningModule(
id="module-1",
name="Routing",
order=0,
knowledge_points=[
KnowledgePoint(
id="kp-1",
name="Adaptive routing",
type=KnowledgeType.MEMORY,
module_id="module-1",
)
],
)
],
)
service = LearningService()
service.store.save(progress)
_, interaction, _ = service.register_question(
path_id,
PendingQuestion(
question_id=question_id,
knowledge_point_id="kp-1",
prompt="What does the router do on a miss?",
question_type="choice",
options=[
"A: give up and report no results",
"B: lower the similarity threshold until something matches",
"C: rewrite the query and retry",
"D: jump back to the router with goto",
],
expected_answer="C",
explanation="A miss is feedback: rewrite the query and retry.",
),
)
return interaction
@pytest.mark.asyncio
async def test_card_answer_is_committed_before_the_turn_runs(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""An answer from a question card is engine state before the tutor reads it.
The card outlives the turn that posed it, so the answer arrives as the next
turn's message. Committing it at turn start is what lets the tutor's first
``mastery_status`` report ``answered`` with the learner's own words instead
of having to pair a bare "C" with a question from scrollback.
"""
_isolate_learning_store(monkeypatch, tmp_path)
from deeptutor.learning.models import InteractionStatus
from deeptutor.learning.service import LearningService
interaction = _open_mastery_question("shared")
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session("session-1")
hold = asyncio.Event()
async def _hold_turn(_execution):
await hold.wait()
monkeypatch.setattr(runtime, "_run_turn", _hold_turn)
payload = {
**_mastery_payload(session["id"], "shared"),
"content": "C",
"mastery_answer": {"question_id": interaction.interaction_id, "text": "C"},
}
_, turn = await runtime.start_turn(payload)
committed = LearningService().store.get_active_interaction("shared")
assert committed is not None
assert committed.status is InteractionStatus.ANSWERED
assert committed.user_answer == "C"
await runtime.cancel_turn(turn["id"])
LearningStore().release_path_lease("shared", turn_id=turn["id"])
@pytest.mark.asyncio
async def test_card_answer_is_ruled_on_before_the_tutor_speaks(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""The verdict reaches the card in milliseconds, not after an LLM round.
Everything it needs was registered when the question was posed, so making
the learner watch their own pick until the tutor got around to calling
``mastery_grade`` was a wait for nothing. The ruling is published as the
same ``mastery_grade`` tool result the card already reads, so it renders
unchanged and survives a reload with the turn.
"""
_isolate_learning_store(monkeypatch, tmp_path)
interaction = _open_mastery_question("shared")
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session("session-1")
hold = asyncio.Event()
async def _hold_turn(_execution):
await hold.wait()
monkeypatch.setattr(runtime, "_run_turn", _hold_turn)
_, turn = await runtime.start_turn(_mastery_payload(session["id"], "shared"))
execution = runtime._executions[turn["id"]]
grade = await runtime._grade_submitted_card_answer(
execution,
path_id="shared",
answer={"question_id": interaction.interaction_id, "text": "C"},
)
assert grade is not None
assert grade["is_correct"] is True
result = grade["result"]
assert result["correct_label"] == "C"
assert result["explanation"].startswith("A miss is feedback")
# The answer key travels to the card only now that the gate has ruled.
published = [
event
for event in execution.events
if event.get("type") == "tool_result"
and (event.get("metadata") or {}).get("tool_metadata", {}).get("mastery_grade")
]
assert len(published) == 1
carried = published[0]["metadata"]["tool_metadata"]["mastery_grade"]["result"]
assert carried["question_id"] == interaction.interaction_id
assert carried["is_correct"] is True
await runtime.cancel_turn(turn["id"])
LearningStore().release_path_lease("shared", turn_id=turn["id"])
@pytest.mark.asyncio
async def test_declining_a_card_drops_the_question_before_the_tutor_speaks(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""A question the learner declined is gone by the time the tutor reads.
The engine holds one open question per path, so a question left open is the
one the tutor's next ``mastery_quiz`` re-presents: without this the learner
could never get past a question they did not want to answer.
"""
_isolate_learning_store(monkeypatch, tmp_path)
from deeptutor.learning.service import LearningService
interaction = _open_mastery_question("shared")
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session("session-1")
hold = asyncio.Event()
async def _hold_turn(_execution):
await hold.wait()
monkeypatch.setattr(runtime, "_run_turn", _hold_turn)
_, turn = await runtime.start_turn(_mastery_payload(session["id"], "shared"))
execution = runtime._executions[turn["id"]]
# A card that is no longer the open question drops nothing: by then it is
# one the learner cannot have been declining.
assert (
await runtime._skip_card_question(
execution, path_id="shared", skip={"question_id": "some-other-question"}
)
is None
)
assert LearningService().store.get_active_interaction("shared") is not None
skip = await runtime._skip_card_question(
execution, path_id="shared", skip={"question_id": interaction.interaction_id}
)
assert skip is not None
assert skip["skipped"] is True
assert skip["question_id"] == interaction.interaction_id
assert LearningService().store.get_active_interaction("shared") is None
# The card reads the same channel a grade arrives on, so it can show that
# this question was set aside rather than staying answerable forever.
published = [
event
for event in execution.events
if event.get("type") == "tool_result"
and (event.get("metadata") or {}).get("tool_metadata", {}).get("mastery_skip_question")
]
assert len(published) == 1
await runtime.cancel_turn(turn["id"])
LearningStore().release_path_lease("shared", turn_id=turn["id"])
@pytest.mark.asyncio
async def test_mastery_path_allows_only_one_live_turn_across_sessions(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
_isolate_learning_store(monkeypatch, tmp_path)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
first_session = await store.ensure_session("session-1")
second_session = await store.ensure_session("session-2")
hold = asyncio.Event()
async def _hold_turn(_execution):
await hold.wait()
monkeypatch.setattr(runtime, "_run_turn", _hold_turn)
_, first_turn = await runtime.start_turn(_mastery_payload(first_session["id"], "shared"))
with pytest.raises(RuntimeError, match="mastery_path_busy"):
await runtime.start_turn(_mastery_payload(second_session["id"], "shared"))
lease = LearningStore().get_path_lease("shared")
assert lease is not None
assert lease.turn_id == first_turn["id"]
rejected = await store.get_active_turn(second_session["id"])
assert rejected is None
await runtime.cancel_turn(first_turn["id"])
LearningStore().release_path_lease("shared", turn_id=first_turn["id"])
@pytest.mark.asyncio
async def test_chat_action_inside_mastery_keeps_path_binding_and_lease(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
_isolate_learning_store(monkeypatch, tmp_path)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session("session-1")
hold = asyncio.Event()
async def _hold_turn(_execution):
await hold.wait()
monkeypatch.setattr(runtime, "_run_turn", _hold_turn)
_, turn = await runtime.start_turn(_mastery_chat_payload(session["id"], "shared"))
lease = LearningStore().get_path_lease("shared")
assert lease is not None
assert lease.turn_id == turn["id"]
detail = await store.get_session(session["id"])
assert detail is not None
assert detail["preferences"]["workspace_mode"] == "mastery_path"
assert detail["preferences"]["capability"] == "chat"
await runtime.cancel_turn(turn["id"])
LearningStore().release_path_lease("shared", turn_id=turn["id"])
@pytest.mark.asyncio
async def test_mastery_turn_rejects_session_from_an_unrelated_topic(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
_isolate_learning_store(monkeypatch, tmp_path)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session("session-1")
await store.update_session_preferences(
session["id"],
{"mastery_path_id": "topic-a"},
)
LearningStore().bind_session("topic-a", session["id"])
with pytest.raises(RuntimeError, match="mastery_session_topic_mismatch"):
await runtime.start_turn(_mastery_payload(session["id"], "topic-b"))
detail = await store.get_session(session["id"])
assert detail is not None
assert detail["preferences"]["mastery_path_id"] == "topic-a"
assert await store.get_active_turn(session["id"]) is None
assert LearningStore().path_id_for_session(session["id"]) == "topic-a"
@pytest.mark.asyncio
async def test_mastery_turn_takes_over_a_path_parked_on_ask_user(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""A turn waiting on the learner must not lock the path forever."""
_isolate_learning_store(monkeypatch, tmp_path)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
first_session = await store.ensure_session("session-1")
second_session = await store.ensure_session("session-2")
parked = asyncio.Event()
async def _park_turn(execution) -> None:
# Mirrors the real turn: flag the ask_user pause, then wait for a
# reply that never comes, then finalize like ``_run_turn`` does.
execution.awaiting_user_reply = True
try:
await parked.wait()
finally:
execution.awaiting_user_reply = False
await store.update_turn_status(execution.turn_id, "cancelled", "Turn cancelled")
async with runtime._lock:
runtime._executions.pop(execution.turn_id, None)
monkeypatch.setattr(runtime, "_run_turn", _park_turn)
_, parked_turn = await runtime.start_turn(_mastery_payload(first_session["id"], "shared"))
while not runtime._executions[parked_turn["id"]].awaiting_user_reply:
await asyncio.sleep(0)
_, resuming_turn = await runtime.start_turn(_mastery_payload(second_session["id"], "shared"))
superseded = await store.get_turn(parked_turn["id"])
assert superseded is not None
assert superseded["status"] == "cancelled"
lease = LearningStore().get_path_lease("shared")
assert lease is not None
assert lease.turn_id == resuming_turn["id"]
assert lease.session_id == second_session["id"]
parked.set()
await runtime.cancel_turn(resuming_turn["id"])
LearningStore().release_path_lease("shared", turn_id=resuming_turn["id"])
@pytest.mark.asyncio
async def test_racing_mastery_start_does_not_steal_pre_task_lease(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
"""The execution marker must exist before the lease acquisition yields."""
_isolate_learning_store(monkeypatch, tmp_path)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
first_session = await store.ensure_session("session-1")
second_session = await store.ensure_session("session-2")
hold_turn = asyncio.Event()
async def _hold_turn(_execution):
await hold_turn.wait()
monkeypatch.setattr(runtime, "_run_turn", _hold_turn)
original_acquire = LearningStore.acquire_path_lease
first_acquired = threading.Event()
release_first_start = threading.Event()
acquisition_count = 0
count_lock = threading.Lock()
def _controlled_acquire(self, *args, **kwargs):
nonlocal acquisition_count
lease = original_acquire(self, *args, **kwargs)
with count_lock:
acquisition_count += 1
is_first = acquisition_count == 1
if is_first:
first_acquired.set()
release_first_start.wait(timeout=5)
return lease
monkeypatch.setattr(LearningStore, "acquire_path_lease", _controlled_acquire)
first_start = asyncio.create_task(
runtime.start_turn(_mastery_payload(first_session["id"], "shared"))
)
assert await asyncio.to_thread(first_acquired.wait, 5)
with pytest.raises(RuntimeError, match="mastery_path_busy"):
await asyncio.wait_for(
runtime.start_turn(_mastery_payload(second_session["id"], "shared")),
timeout=2,
)
release_first_start.set()
_, first_turn = await first_start
persisted = await store.get_turn(first_turn["id"])
assert persisted is not None
assert persisted["status"] == "running"
assert LearningStore().get_path_lease("shared").turn_id == first_turn["id"]
await runtime.cancel_turn(first_turn["id"])
@pytest.mark.asyncio
async def test_mastery_path_does_not_steal_apparently_orphaned_lease(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
_isolate_learning_store(monkeypatch, tmp_path)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
stale_session = await store.ensure_session("stale-session")
stale_turn = await store.create_turn(stale_session["id"], capability="mastery_path")
LearningStore().acquire_path_lease(
"shared",
stale_session["id"],
stale_turn["id"],
)
runtime = TurnRuntimeManager(store)
new_session = await store.ensure_session("new-session")
hold = asyncio.Event()
async def _hold_turn(_execution):
await hold.wait()
monkeypatch.setattr(runtime, "_run_turn", _hold_turn)
with pytest.raises(RuntimeError, match="mastery_path_busy"):
await runtime.start_turn(_mastery_payload(new_session["id"], "shared"))
persisted = await store.get_turn(stale_turn["id"])
lease = LearningStore().get_path_lease("shared")
assert persisted is not None
assert persisted["status"] == "running"
assert lease is not None
assert lease.turn_id == stale_turn["id"]
LearningStore().release_path_lease("shared", turn_id=stale_turn["id"])
@pytest.mark.asyncio
async def test_mastery_turn_cannot_steal_administrative_path_lease(
monkeypatch: pytest.MonkeyPatch, tmp_path
) -> None:
_isolate_learning_store(monkeypatch, tmp_path)
learning_store = LearningStore()
learning_store.acquire_path_lease(
"shared",
"__path_api__",
"api-operation",
bind_session=False,
)
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
session = await store.ensure_session("session-1")
try:
with pytest.raises(RuntimeError, match="mastery_path_busy"):
await runtime.start_turn(_mastery_payload(session["id"], "shared"))
lease = learning_store.get_path_lease("shared")
assert lease is not None
assert lease.turn_id == "api-operation"
finally:
learning_store.release_path_lease("shared", turn_id="api-operation")
@pytest.mark.asyncio
async def test_a_mid_turn_path_switch_is_pushed_to_the_client(tmp_path) -> None:
"""Otherwise the composer keeps naming the path the turn started on."""
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
execution = _TurnExecution(
turn_id="turn-1",
session_id="session-1",
capability="mastery_path",
payload={},
)
await runtime._publish_mastery_path_change(
execution,
capability_name="mastery_path",
started_on="calculus",
ended_on="algebra",
)
pushed = [event for event in execution.events if event["type"] == "session_meta"]
assert len(pushed) == 1
assert pushed[0]["metadata"]["mastery_path_id"] == "algebra"
@pytest.mark.asyncio
async def test_no_path_push_when_the_turn_never_moved(tmp_path) -> None:
store = SQLiteSessionStore(tmp_path / "chat_history.db")
runtime = TurnRuntimeManager(store)
execution = _TurnExecution(
turn_id="turn-1", session_id="session-1", capability="mastery_path", payload={}
)
await runtime._publish_mastery_path_change(
execution, capability_name="mastery_path", started_on="calculus", ended_on="calculus"
)
await runtime._publish_mastery_path_change(
execution, capability_name="chat", started_on="", ended_on="algebra"
)
assert [event for event in execution.events if event["type"] == "session_meta"] == []
@pytest.mark.asyncio
@pytest.mark.parametrize("preparation_fails", [False, True])
async def test_context_preparation_usage_is_included_in_durable_turn_total(
monkeypatch, tmp_path, preparation_fails
):
"""#1920/#1926: summary work is paid before the capability starts."""
from unittest.mock import AsyncMock, MagicMock
from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability
from deeptutor.runtime.orchestrator import ChatOrchestrator
from deeptutor.services.llm.metrics import CallMeasurement, current_usage
store = SQLiteSessionStore(tmp_path / "usage.db")
runtime = TurnRuntimeManager(store)
def measure(tokens):
meter = CallMeasurement(model="test", provider="test")
meter.finish(
SimpleNamespace(
usage={"prompt_tokens": tokens, "completion_tokens": 1, "total_tokens": tokens + 1}
)
)
class Builder:
async def build(self, **kwargs):
measure(100)
if preparation_fails:
raise RuntimeError("Preparation unavailable")
return SimpleNamespace(
conversation_history=[],
conversation_summary="",
context_text="",
token_count=0,
budget=0,
)
class Capability(TurnCapability):
manifest = CapabilityManifest(name="chat", description="Usage regression")
async def run(self, context, stream):
measure(20)
await stream.content("The answer", source="chat")
orchestrator = ChatOrchestrator.__new__(ChatOrchestrator)
orchestrator._cap_registry = MagicMock()
orchestrator._cap_registry.get.return_value = Capability()
orchestrator._tool_registry = MagicMock()
bus = MagicMock()
bus.publish = AsyncMock()
monkeypatch.setattr("deeptutor.runtime.orchestrator.get_event_bus", lambda: bus)
monkeypatch.setattr("deeptutor.runtime.orchestrator.ChatOrchestrator", lambda: orchestrator)
monkeypatch.setattr(runtime, "_create_context_builder", lambda **kwargs: Builder())
monkeypatch.setattr(runtime, "_maybe_generate_session_title", AsyncMock())
session, turn = await runtime.start_turn(
{"content": "Continue", "capability": "chat", "tools": []}
)
events = [e async for e in runtime.subscribe_turn(turn["id"])]
done = next(e for e in events if e["type"] == "done")
assert done["metadata"]["usage_summary"]["prompt_tokens"] == (100 if preparation_fails else 120)
assert done["metadata"]["usage_summary"]["total_calls"] == (1 if preparation_fails else 2)
messages = await store.get_messages(session["id"])
if preparation_fails:
assert done["metadata"]["status"] == "failed"
assert current_usage.get() is None
return
stored = next(e for e in messages[-1]["events"] if e["type"] == "done")
assert stored["metadata"]["usage_summary"] == done["metadata"]["usage_summary"]
assert current_usage.get() is None