DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
Merge dev into preview, preserving preview features
Bingxi Zhao (Frank)6bbcc00c55a9
diff --cc README.mdindex 0fb3c97ee,57e6ece07..0c3e51055--- a/README.md+++ b/README.md@@@ -1005,10 -1007,10 +1007,10 @@@ The repo ships a root [`SKILL.md`](SKIL| `deeptutor stop [--home PATH]` | Stop a launcher started with `--detach` || `deeptutor serve [--port PORT]` | Start only the FastAPI backend || `deeptutor workspace show/set/reset` | Inspect, select, or restore the per-user Content Workspace |-| `deeptutor run <capability> <message>` | Run a single capability turn (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `course_study`, `audio_overview`); add `--format json` for NDJSON output |+| `deeptutor run <capability> <message>` | Run a single capability turn (`chat`, `ask_questions`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`, `immersive_reading`, `audio_overview`); add `--format json` for NDJSON output || `deeptutor chat` | Interactive REPL with capability, tool, KB, notebook, and history controls || `deeptutor partner list/create/start/stop` | Manage IM-connected partners |- | `deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync` | Manage knowledge bases, connect Kiwix archives, score retrieval quality against a QA set, and synchronize registered GitHub/web sources (with source add/remove commands) |+ | `deeptutor kb list/info/create/connect-kiwix/add/search/eval/eval-diff/set-default/delete/list-sources/sync` | Manage knowledge bases, connect Kiwix archives, score and compare retrieval runs, and synchronize registered GitHub/web sources (with source add/remove commands) || `deeptutor skill search/install/list/remove/login/logout/publish/update` | Manage skills, install from hubs, and publish your own (`eduhub:<slug>` by default, see Ecosystem) || `deeptutor memory show/clear` | Inspect L2/L3 memory docs or clear L1/all memory || `deeptutor session list/show/open/rename/delete` | Manage shared sessions |diff --cc deeptutor/agents/loop/loop_host.pyindex 840db1ac7,000000000..1249d18damode 100644,000000..100644--- a/deeptutor/agents/loop/loop_host.py+++ b/deeptutor/agents/loop/loop_host.py@@@ -1,384 -1,0 +1,413 @@@+"""Provider/tool/capability effects shared by both scheduler implementations.++This migration adapter owns conversation data, never loop scheduling decisions.+It runs inside the originating Python task to preserve account/workspace scopes.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++from deeptutor.runtime.agentic.messages import (+ assistant_message_with_tool_calls,+ extend_transient_model_messages,+)+from deeptutor.runtime.agentic.tool_dispatch import DispatchOutcome+from deeptutor.services.llm import LLMReasoningBudgetExhausted, finish_was_truncated++from . import loop_state as values++if TYPE_CHECKING:+ from .agent_loop import AgentLoop+++class AgentLoopHost:+ def __init__(+ self,+ loop: AgentLoop,+ messages: list[dict[str, Any]],+ state: values.AgentLoopState,+ checkpoint_boundary: int,+ ) -> None:+ self.loop = loop+ self.pipeline = loop.pipeline+ self.context = loop.context+ self.stream = loop.stream+ self.messages = messages+ self.state = state+ self.checkpoint_boundary = checkpoint_boundary+ self.continued: list[str] = []+ self.result: values.LLMCallResult | None = None+ self.dispatch: DispatchOutcome | None = None+ self.outcome: values.LoopOutcome | None = None+ self.redirect = ""+ self.override: str | None = None+ self.override_after_tools = False++ self.recovery_tools: frozenset[str] | None = None++ self.recovery_schemas: list[dict[str, Any]] | None = None++ async def invoke(self, operation: str, args: dict[str, Any], state: dict[str, Any]) -> Any:+ operations = {++ "prepare_recovery": self.prepare_recovery,+ "begin_settlement": self.begin_settlement,+ "call_round": self.call_round,+ "continue_truncated": self.continue_truncated,+ "raise_reasoning_budget": self.raise_reasoning_budget,+ "recover_empty": self.recover_empty,+ "check_finish": self.check_finish,+ "redirect_finish": self.redirect_finish,+ "reject_finish": self.reject_finish,+ "finish": self.finish,+ "dispatch_tools": self.dispatch_tools,+ "resolve_pause": self.resolve_pause,+ "after_tools": self.after_tools,+ "terminate": self.terminate,+ "forced_finish": self.forced_finish,+ }+ if operation not in operations or not isinstance(args, dict):+ raise ValueError("Unknown chat host operation")+ self.sync_state(state)+ return await operations[operation](**args)++ def sync_state(self, state: dict[str, Any]) -> None:+ for name in (+ "rounds",+ "exploration_rounds",+ "settlement_rounds",+ "tool_steps",+ "reasoning_budget_recoveries",+ ):+ value = state.get(name)+ if not isinstance(value, int) or isinstance(value, bool) or value < 0:+ raise ValueError("Invalid chat loop state")+ setattr(self.state, name, value)++ async def warning(self, key: str, default: str) -> None:+ await self.stream.progress(+ self.pipeline._t(key, default=default),+ source=self.loop.source,+ stage=self.loop.stage,+ metadata={"trace_kind": "warning"},+ )+++ async def prepare_recovery(self) -> dict[str, bool]:++ recovery = self.pipeline._capability_settlement_recovery(self.context)++ if recovery is None:++ return {"available": False, "rejected": False}++ instruction, names = recovery++ self.recovery_schemas = [++ schema for schema in self.loop.tool_schemas or []++ if (schema.get("function") or {}).get("name") in names++ ]++ self.recovery_tools = frozenset(++ schema["function"]["name"] for schema in self.recovery_schemas++ )++ if not self.recovery_tools:++ return {"available": False, "rejected": True}++ self.loop._append_loop_instruction(self.messages, instruction)++ return {"available": True, "rejected": False}+++ async def begin_settlement(self) -> None:+ await self.loop._begin_settlement(self.messages)++ async def read_inbox(self) -> None:+ """Hand the model what the learner sent while the turn was running.++ Read at every step boundary — before each model call, so after the+ tool batch in flight — and appended as the learner's own words; the+ trace row puts the message in the transcript where it was read.+ """+ drain = self.context.runtime.drain_user_inputs+ inputs = drain() if drain is not None else []+ if not inputs:+ return+ lead = self.pipeline._t(+ "loop.user_sent_while_working",+ default=(+ "[The user sent this while you were working. Take it into account from "+ "here on: answer it, or adjust what you are doing.]"+ ),+ )+ said = "\n\n".join(str(item["content"]) for item in inputs)+ self.loop._append_loop_instruction(self.messages, f"{lead}\n{said}")+ await self.stream.progress(+ "",+ source=self.loop.source,+ stage=self.loop.stage,+ metadata={+ "trace_kind": "user_input",+ "user_inputs": [+ {"command_id": item["command_id"], "content": item["content"]}+ for item in inputs+ ],+ },+ )++ async def call_round(self, *, settling: bool, first: bool) -> dict[str, bool]:+ self.override_after_tools = False+ await self.read_inbox()+ self.result = await self.loop._call_llm(+ messages=self.messages,+ label=self.pipeline._t("labels.final_response", default="Final response")+ if settling+ else self.pipeline._t("labels.exploring", default="Exploring"),+ call_kind="agent_loop_round",+ trace_role="response" if settling else "explore",+ max_tokens=self.pipeline.loop_max_tokens,- tool_schemas=self.loop.tool_schemas,++ tool_schemas=self.recovery_schemas++ if self.recovery_tools is not None++ else self.loop.tool_schemas,+ defer_visible_output=self.pipeline._capability_buffers_visible_output(self.context),+ tool_choice=self.pipeline.initial_tool_choice if first else None,+ )++ rejected = self.recovery_tools is not None and any(++ str(call.get("name") or "").strip() not in self.recovery_tools++ for call in self.result.tool_calls++ )++ if rejected:++ await self.loop._discard_deferred_output(self.result)+ return {++ "recoveryRejected": rejected,+ "hasTools": bool(self.result.tool_calls),+ "hasText": bool(self.loop._clean(self.result.text)),+ "truncated": finish_was_truncated(self.result.finish_reason),+ "reasoningBudgetExhausted": values._reasoning_budget_exhausted(+ self.result, self.pipeline.loop_max_tokens+ ),+ }++ async def raise_reasoning_budget(self) -> None:+ assert self.result is not None+ await self.loop._release_deferred_output(self.result)+ raise LLMReasoningBudgetExhausted(+ self.pipeline._t(+ "notices.reasoning_budget_exhausted",+ default=(+ "The model exhausted its output budget on internal reasoning twice without "+ "producing an answer or tool action. Please retry, lower reasoning effort, "+ "or split the task into smaller steps."+ ),+ ),+ diagnostics={+ "rounds": self.state.rounds,+ "reasoning_chars": self.result.reasoning_chars,+ "completion_tokens": self.result.usage.get("completion_tokens"),+ "reasoning_tokens": self.result.usage.get("reasoning_tokens"),+ },+ )++ async def continue_truncated(self) -> None:+ result = self.result+ assert result is not None+ await self.loop._release_deferred_output(result)+ await self.warning(+ "notices.output_truncated",+ "The model output reached its token limit; asked it to continue.",+ )+ if result.visible_text:+ self.continued.append(result.visible_text)+ if values._has_replayable_assistant_state(result):+ self.messages.append(values._assistant_round_message(result))+ if result.visible_text:+ instruction = self.pipeline._t(+ "loop.continue_truncated",+ default=(+ "Your previous response stopped at the token limit. Continue from where it ended "+ "without repeating it, and complete the user-facing answer."+ ),+ )+ else:+ instruction = self.pipeline._t(+ "loop.continue_truncated_reasoning",+ default=(+ "Your previous round spent its entire output budget on internal reasoning and hit "+ "the token limit before writing anything — so there is nothing to continue from, "+ "and reasoning it through again will end the same way. Act now instead: make the "+ "tool call, or write the answer with the judgement you already have. Good enough "+ "is required; optimal is not. Do not redesign or second-guess what you had already settled on."+ ),+ )+ self.loop._append_loop_instruction(self.messages, instruction)++ async def recover_empty(self, *, force: bool) -> None:+ assert self.result is not None+ await self.warning(+ "notices.empty_finish_nudged",+ "The round produced only internal reasoning; asked the model to continue.",+ )+ if values._has_replayable_assistant_state(self.result):+ self.messages.append(values._assistant_round_message(self.result))+ if force:+ instruction = self.pipeline._t(+ "loop.repeat_reasoning_only_nudge",+ default=(+ "Your previous rounds produced only internal reasoning — no tool call and no "+ "user-facing answer. Do not reason further. Select the most likely next action and produce it now."+ ),+ )+ else:+ instruction = self.pipeline._t(+ "loop.finish_empty_nudge",+ default=(+ "Your previous round produced only internal reasoning — no tool call and no "+ "user-facing answer. Continue now: either call the tools to execute your plan, "+ "or write the final user-facing answer directly."+ ),+ )+ self.loop._append_loop_instruction(self.messages, instruction)++ async def check_finish(self) -> dict[str, bool]:+ assert self.result is not None+ text = self.loop._clean(self.result.text)+ self.redirect = self.pipeline._capability_finish_instruction(self.context, text)+ if self.redirect:+ await self.loop._discard_deferred_output(self.result)+ return {"redirect": True, "override": False}+ self.override = self.pipeline._capability_final_text_override(self.context, text)+ return {"redirect": False, "override": self.override is not None}++ async def redirect_finish(self) -> None:+ assert self.result is not None+ if self.result.text:+ self.messages.append(values._assistant_round_message(self.result))+ self.loop._append_loop_instruction(self.messages, self.redirect)++ async def reject_finish(self) -> None:+ self.outcome = await self.loop._reject_capability_finish()++ async def finish(self, *, override: bool) -> None:+ result = self.result+ assert result is not None+ if override:+ assert self.override is not None+ if not self.override_after_tools:+ await self.loop._discard_deferred_output(result)+ if not self.context.capability_output.answer_published:+ await self.pipeline._emit_protocol_fallback_final_response(+ self.stream, self.override+ )+ self.context.capability_output.answer_published = True+ self.outcome = await self.loop._finalize_finish(+ self.override, continued_answer_parts=self.continued, allow_empty=True+ )+ return+ await self.loop._release_deferred_output(result)+ self.messages.append(values._assistant_round_message(result))+ self.outcome = await self.loop._finalize_finish(+ self.loop._clean(result.text),+ visible_text=result.visible_text,+ continued_answer_parts=self.continued,+ provider_response_state=values._provider_response_state(+ result.response_output_items, result.reasoning_content, result.thinking_blocks+ ),+ )++ async def dispatch_tools(self) -> dict[str, bool]:+ result = self.result+ assert result is not None+ if finish_was_truncated(result.finish_reason):+ await self.warning(+ "notices.tool_call_truncated",+ (+ "The model reached its output token limit while writing a tool call, so the call "+ "may be incomplete. If this repeats, raise this capability's max tokens or pick "+ "a model that reasons less."+ ),+ )+ tool_names = tuple(str(call.get("name") or "") for call in result.tool_calls)+ policy = self.pipeline._capability_tool_round_output_policy(+ self.context, self.loop._clean(result.text), tool_names+ )+ if policy == "discard":+ await self.loop._discard_deferred_output(result)+ else:+ await self.loop._release_deferred_output(result)+ assistant = assistant_message_with_tool_calls(+ result.text,+ result.tool_calls,+ reasoning_content=result.reasoning_content or None,+ thinking_blocks=result.thinking_blocks or None,+ )+ provider_state = values._provider_response_state(+ result.response_output_items, result.reasoning_content, result.thinking_blocks+ )+ if provider_state is not None:+ assistant["_provider_response_state"] = provider_state+ self.messages.append(assistant)+ self.dispatch = await self.pipeline._dispatch_tool_calls(+ tool_calls=result.tool_calls,+ context=self.context,+ stream=self.stream,+ iteration_index=self.state.tool_steps,+ stage=self.loop.stage,+ )+ self.state.sources.extend(self.dispatch.sources)+ self.messages.extend(self.dispatch.tool_messages)+ extend_transient_model_messages(+ self.loop._transient_model_messages, self.dispatch.model_messages+ )+ return {"pause": self.dispatch.pause}++ async def resolve_pause(self) -> bool:+ assert self.dispatch is not None+ resumed = await self.pipeline._await_user_reply_and_resolve(+ context=self.context, stream=self.stream, dispatch=self.dispatch+ )+ if not resumed:+ self.outcome = values.LoopOutcome(final_text="", completed=False)+ return resumed++ async def after_tools(self) -> dict[str, bool]:+ assert self.dispatch is not None+ self.checkpoint_boundary = self.loop._fold_context_checkpoint(+ messages=self.messages,+ dispatch=self.dispatch,+ checkpoint_boundary=self.checkpoint_boundary,+ )+ self.override = self.pipeline._capability_final_text_override(self.context, "")+ self.override_after_tools = True+ return {"override": self.override is not None, "terminate": self.dispatch.terminate}++ async def terminate(self) -> None:+ assert self.dispatch is not None+ payload = self.dispatch.terminate_payload or {}+ await self.pipeline._emit_terminator_final_response(self.stream, payload)+ self.outcome = values.LoopOutcome(+ final_text=values._join_answer_parts(self.continued, str(payload.get("content") or "")),+ completed=True,+ )++ async def forced_finish(self, *, reason: str, error: str) -> dict[str, int]:+ before = self.state.rounds+ self.outcome = await self.loop._forced_finish(+ self.messages,+ self.state,+ reason=reason,+ error=error,+ continued_answer_parts=self.continued,+ )+ return {"extraRounds": self.state.rounds - before}+++async def run_loop_with_host(+ loop: AgentLoop,+ *,+ messages: list[dict[str, Any]],+ state: values.AgentLoopState,+ checkpoint_boundary: int,+ scheduler: str,+ config: dict[str, int],+) -> values.LoopOutcome:+ host = AgentLoopHost(loop, messages, state, checkpoint_boundary)+ if scheduler == "typescript":+ from deeptutor.runtime.ts_engine import get_engine_client++ final_state = await get_engine_client().run(host, config)+ else:+ from deeptutor.agents.loop.python_scheduler import run_loop++ final_state = await run_loop(host, config)+ host.sync_state(final_state)+ if host.outcome is None:+ raise RuntimeError("Chat scheduler completed without an outcome")+ return host.outcomediff --cc deeptutor/agents/loop/python_scheduler.pyindex d55955926,000000000..2957d77e6mode 100644,000000..100644--- a/deeptutor/agents/loop/python_scheduler.py+++ b/deeptutor/agents/loop/python_scheduler.py@@@ -1,90 -1,0 +1,104 @@@+"""Reference scheduler for installs without Node; effects live in loop_host.++Keep this small control flow aligned with packages/chat-engine/src/core/run-loop.ts.+The existing behavior suite exercises both backends against the same adapters.+"""++from __future__ import annotations++from typing import Any+++from deeptutor.core.capability_protocol import CapabilityPrerequisiteError+from deeptutor.services.llm import LLMProviderTransportError+++async def run_loop(host: Any, config: dict[str, int]) -> dict[str, int]:+ state = dict(+ rounds=0,+ exploration_rounds=0,+ settlement_rounds=0,+ tool_steps=0,+ reasoning_budget_recoveries=0,+ )+ settlement_started = False+ empty_recoveries = 0+ finish_redirect_used = False++ recovery_used = False++ async def invoke(operation: str, **args: Any) -> Any:+ return await host.invoke(operation, args, dict(state))++ async def force_finish(reason: str = "budget", error: str = "") -> dict[str, int]:+ result = await invoke("forced_finish", reason=reason, error=error)+ state["rounds"] += result["extraRounds"]+ return state++ while True:+ settling = state["exploration_rounds"] >= config["explorationBudget"]+ if settling:+ if state["settlement_rounds"] >= config["settlementBudget"]:- return await force_finish()++ if recovery_used:++ await invoke("reject_finish")++ return state++ recovery = await invoke("prepare_recovery")++ if recovery["rejected"]:++ await invoke("reject_finish")++ return state++ if not recovery["available"]:++ return await force_finish()++ recovery_used = True+ if not settlement_started:+ await invoke("begin_settlement")+ settlement_started = True+ try:+ result = await invoke("call_round", settling=settling, first=state["rounds"] == 0)+ except Exception as exc:- if state["rounds"] == 0 or (++ if isinstance(exc, CapabilityPrerequisiteError) or state["rounds"] == 0 or (+ isinstance(exc, LLMProviderTransportError) and exc.partial_response+ ):+ raise+ return await force_finish("error", str(exc))+ state["rounds"] += 1+ state["settlement_rounds" if settling else "exploration_rounds"] += 1++ if result.get("recoveryRejected"):++ await invoke("reject_finish")++ return state+ if not result["hasTools"]:+ if result["truncated"] or result["reasoningBudgetExhausted"]:+ if result["reasoningBudgetExhausted"]:+ if state["reasoning_budget_recoveries"] >= 1:+ await invoke("raise_reasoning_budget")+ state["reasoning_budget_recoveries"] += 1+ await invoke("continue_truncated")+ continue+ if not result["hasText"]:+ empty_recoveries += 1+ force = empty_recoveries >= config["emptyRecoveryBudget"]+ await invoke("recover_empty", force=force)+ if force:+ return await force_finish()+ continue+ decision = await invoke("check_finish")+ if decision["redirect"]:+ if finish_redirect_used:+ await invoke("reject_finish")+ return state+ finish_redirect_used = True+ await invoke("redirect_finish")+ continue+ await invoke("finish", override=decision["override"])+ return state++ dispatch = await invoke("dispatch_tools")+ state["tool_steps"] += 1+ if dispatch["pause"]:+ if await invoke("resolve_pause"):+ continue+ return state+ decision = await invoke("after_tools")+ if decision["override"]:+ await invoke("finish", override=True)+ return state+ if decision["terminate"]:+ await invoke("terminate")+ return statediff --cc deeptutor/api/routers/auth.pyindex 660131a57,b3cb5df46..91aa0ae18--- a/deeptutor/api/routers/auth.py+++ b/deeptutor/api/routers/auth.py@@@ -712,13 -705,22 +713,27 @@@ async def require_learning_surface_: TokenPayload | None = Depends(require_auth),) -> None:"""Second-stage default-deny guard for configured learning accounts."""- from deeptutor.multi_user.learning_access import assert_learning_surface+ from deeptutor.multi_user.learning_access import (+ assert_learning_surface,+ learning_surface_allowed,+ )++ route_path = _resolved_route_path(request)+ # The landing page combines independent learning surfaces (#1987). Admit+ # any granted surface; the handler filters its readers with the same policy.+ if (+ request.method == "GET"+ and request.url.path == "/api/dashboard/learning-index"+ and route_path == "/api/dashboard/learning-index"+ and any(learning_surface_allowed(surface) for surface in ("books", "chat", "reading"))+ ):+ return+ # This aggregate filters each source by the current policy itself. Exact+ # GET only: it must never open the rest of the dashboard to learners.+ if request.method == "GET" and request.url.path == "/api/dashboard/learning-index":+ return+try:assert_learning_surface(_learning_surface_for_path(diff --cc deeptutor/api/routers/dashboard.pyindex b846f1105,6769e3ae8..f9a91ab13--- a/deeptutor/api/routers/dashboard.py+++ b/deeptutor/api/routers/dashboard.py@@@ -136,24 -101,27 +126,36 @@@ async def get_learning_index()return [rowfor row in rows- if (row.get("preferences") or {}).get("workspace_mode") == "immersive_watching"- or (row.get("preferences") or {}).get("capability") == "immersive_watching"+ if not (row.get("preferences") or {}).get("archived")+ and (+ (row.get("preferences") or {}).get("workspace_mode") == "immersive_watching"+ or (row.get("preferences") or {}).get("capability") == "immersive_watching"+ )]- if allowed is None or "reading" in allowed:- result["watching"] = await _workspace_rows(watching)- if allowed is None or "chat" in allowed:-- async def practice():- from deeptutor.services.session import get_sqlite_session_store-- return await get_sqlite_session_store().list_notebook_navigation()-- result["practice"] = await _workspace_rows(practice)- return {"sources": result, "failed": []}++ async def practice():++ from deeptutor.services.session import get_sqlite_session_store++++ return await get_sqlite_session_store().list_notebook_navigation()+++ result = {}+ failed = []+ for kind, surface, reader in (+ ("books", "books", books),+ ("mastery", "chat", mastery),+ ("reading", "reading", reading),+ ("watching", "reading", watching),++ ("practice", "chat", practice),+ ):+ # Calling a route function directly bypasses its HTTP dependencies.+ # Never load a source that the learner could not open individually.+ result[kind] = []+ if not learning_surface_allowed(surface):+ continue+ result[kind], unavailable = await read_workspace_indexes(reader)+ if unavailable:+ failed.append(kind)+ return {"sources": result, "failed": failed}@router.get("/source-library/{kind}")diff --cc deeptutor/core/turn_request.pyindex da85712a9,8523f9121..30accfd6b--- a/deeptutor/core/turn_request.py+++ b/deeptutor/core/turn_request.py@@@ -93,22 -93,20 +93,34 @@@ class MasteryCardAnswer(BaseModel)question_id: str = Field(min_length=1)text: str = Field(min_length=1)+ answers: dict[str, StrictStr] | None = Field(default=None, min_length=1, max_length=4)++ @field_validator("answers")+ @classmethod+ def validate_group_answers(cls, value: dict[str, str] | None) -> dict[str, str] | None:+ if value is not None:+ for question_id, answer in value.items():+ if not question_id.strip() or len(question_id) > 200:+ raise ValueError("group answers require bounded nonempty question IDs")+ if not answer.strip() or len(answer) > 8000:+ raise ValueError("group answers require bounded nonempty answer text")+ return value+class NoteGeneration(BaseModel):+ """The learning block on the open note page this turn fills in.++ Sent by the note companion when a block's own "Generate" runs. The server+ owns the instructions that follow from it, so the learner's message stays+ exactly what they see in the conversation.+ """++ model_config = ConfigDict(extra="forbid")++ block_id: str = Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$")+ kind: str = Field(default="", max_length=32)++class MasteryCardSkip(BaseModel):"""A question the learner dropped instead of answering.diff --cc deeptutor/runtime/coordination/memory.pyindex d4acaf600,be4d6d610..43ccb248d--- a/deeptutor/runtime/coordination/memory.py+++ b/deeptutor/runtime/coordination/memory.py@@@ -148,8 -97,15 +148,15 @@@ class MemoryCoordinatorasync def acknowledge_expired_turn(self, turn_id: str) -> None:async with self._lock:- self._known_turns.discard(turn_id)lease = self._turn_leases.get(turn_id)+ if self._active(lease):+ return+ self._known_turns.discard(turn_id)+ # Recovery has verified the durable terminal row. Keeping these+ # payloads forever leaks every completed conversation (#1971).+ self._events.pop(turn_id, None)+ for _, command in self._commands.pop(turn_id, []):- self._command_ids.discard(command.command_id)++ self._command_ids.pop(command.command_id, None)if lease is not None and not self._active(lease):self._turn_leases.pop(turn_id, None)if self._session_turns.get(lease.session_id) == turn_id:diff --cc deeptutor/runtime/ts_engine/client.pyindex a63982f64,000000000..397e74808mode 100644,000000..100644--- a/deeptutor/runtime/ts_engine/client.py+++ b/deeptutor/runtime/ts_engine/client.py@@@ -1,344 -1,0 +1,347 @@@+"""Multiplex turn-scoped host calls over one private Node child per event loop.++The reader only routes frames. Host operations inherit the originating turn's+context, so user/workspace/model ContextVars cannot leak between concurrent turns.+There is deliberately no mid-turn fallback or retry after a worker failure.+"""++from __future__ import annotations++import asyncio+import atexit+from contextlib import suppress+import json+import os+from pathlib import Path+import shutil+from typing import Any, Protocol+import uuid++_MAX_FRAME = 48 * 1024 * 1024+_MAX_RUNS = 128+_IDLE_WORKER_SECONDS = 30.0+_clients: dict[asyncio.AbstractEventLoop, EngineClient] = {}+++class Host(Protocol):+ async def invoke(self, operation: str, args: dict[str, Any], state: dict[str, Any]) -> Any: ...+++class EngineUnavailableError(RuntimeError):+ """A scheduler failure must fail the turn without replaying side effects."""+++class EngineClient:+ def __init__(self) -> None:+ self._process: asyncio.subprocess.Process | None = None+ self._reader: asyncio.Task[None] | None = None+ self._startup = asyncio.Lock()+ self._write_lock = asyncio.Lock()+ self._runs: dict[str, asyncio.Queue[dict[str, Any] | Exception]] = {}+ self._idle_handle: asyncio.TimerHandle | None = None+ self._closed = False++ async def _ensure_started(self) -> None:+ async with self._startup:+ if self._closed:+ raise EngineUnavailableError("TypeScript scheduler client is closed")+ self._cancel_idle_close()+ if self._process is not None and self._process.returncode is None:+ return+ if self._reader is not None:+ await self._reader+ entry = (+ Path(__file__).resolve().parents[3]+ / "packages/chat-engine/dist/src/transport/stdio.js"+ )+ node = shutil.which(os.getenv("DEEPTUTOR_NODE_EXECUTABLE", "node"))+ if node is None or not entry.is_file():+ raise EngineUnavailableError(+ "TypeScript chat engine needs Node >=22 and a build: "+ "cd packages/chat-engine && npm ci && npm run build. "+ "Set DEEPTUTOR_CHAT_ENGINE=python to select the Python scheduler."+ )+ self._process = await asyncio.create_subprocess_exec(+ node,+ str(entry),+ stdin=asyncio.subprocess.PIPE,+ stdout=asyncio.subprocess.PIPE,+ # stdout is private protocol; do not expose child diagnostics.+ stderr=asyncio.subprocess.DEVNULL,+ limit=_MAX_FRAME,+ # The worker receives per-turn credentials through its pipe,+ # never through NODE_OPTIONS or arbitrary startup hooks.+ env={+ key: os.environ[key]+ for key in ("PATH", "SYSTEMROOT", "SystemRoot", "WINDIR")+ if key in os.environ+ },+ )+ self._reader = asyncio.create_task(+ self._read(self._process), name="ts-chat-engine-reader"+ )++ async def _read(self, process: asyncio.subprocess.Process) -> None:+ assert process.stdout is not None+ try:+ while line := await process.stdout.readline():+ frame = json.loads(line)+ if not isinstance(frame, dict) or frame.get("v") != 1:+ raise EngineUnavailableError("Invalid TypeScript scheduler protocol")+ queue = self._runs.get(str(frame.get("runId", "")))+ if queue is not None:+ queue.put_nowait(frame)+ except (Exception, asyncio.CancelledError):+ pass+ finally:+ if process.returncode is None:+ with suppress(ProcessLookupError):+ process.terminate()+ for queue in tuple(self._runs.values()):+ with suppress(asyncio.QueueFull):+ queue.put_nowait(+ EngineUnavailableError("TypeScript scheduler stopped during turn")+ )+ await process.wait()++ async def _send(self, frame: dict[str, Any]) -> None:+ payload = (json.dumps({"v": 1, **frame}, ensure_ascii=False) + "\n").encode()+ if len(payload) > _MAX_FRAME:+ raise EngineUnavailableError("TypeScript scheduler frame exceeds limit")+ async with self._write_lock:+ process = self._process+ if process is None or process.stdin is None or process.returncode is not None:+ raise EngineUnavailableError("TypeScript scheduler is unavailable")+ try:+ process.stdin.write(payload)+ await process.stdin.drain()+ except (BrokenPipeError, ConnectionResetError) as exc:+ raise EngineUnavailableError("TypeScript scheduler connection closed") from exc++ async def run(self, host: Host, config: dict[str, int]) -> dict[str, Any]:+ await self._ensure_started()+ if len(self._runs) >= _MAX_RUNS:+ raise EngineUnavailableError("TypeScript scheduler is at capacity")+ run_id = uuid.uuid4().hex+ queue: asyncio.Queue[dict[str, Any] | Exception] = asyncio.Queue(maxsize=4)+ self._runs[run_id] = queue+ failures: dict[str, Exception] = {}+ try:+ await self._send({"kind": "run", "runId": run_id, "config": config})+ while True:+ # Scheduler decisions are local and bounded. Provider/tool/user+ # waits happen in host.invoke below and have their own policy.+ frame = await asyncio.wait_for(queue.get(), timeout=15)+ if isinstance(frame, Exception):+ raise frame+ kind = frame.get("kind")+ if kind == "complete":+ return frame["state"]+ if kind == "failed":+ original = failures.get(str(frame.get("callId", "")))+ if original is not None:+ raise original+ raise EngineUnavailableError(str(frame.get("message", "Scheduler failed")))+ if kind != "call":+ raise EngineUnavailableError("Unknown scheduler operation")+ call_id = str(frame["callId"])+ reply: dict[str, Any] = {"kind": "reply", "runId": run_id, "callId": call_id}+ try:+ result = await self._invoke_host(host, frame)+ reply.update(ok=True, result=result)+ except Exception as exc:+ # Keep the original typed exception in-process. Node only+ # needs to know whether salvage is safe after visible output.++ from deeptutor.core.capability_protocol import CapabilityPrerequisiteError+++ failures[call_id] = exc+ reply.update(+ ok=False,+ error={+ "message": str(exc)[:4096],+ "partialResponse": bool(getattr(exc, "partial_response", False)),++ "fatal": isinstance(exc, CapabilityPrerequisiteError),+ },+ )+ await self._send(reply)+ finally:+ self._runs.pop(run_id, None)+ with suppress(Exception, asyncio.CancelledError):+ await self._send({"kind": "cancel", "runId": run_id})+ if not self._runs and not self._closed:+ self._cancel_idle_close()+ self._idle_handle = asyncio.get_running_loop().call_later(+ _IDLE_WORKER_SECONDS, self._schedule_idle_close+ )++ async def run_native(+ self, host: Host, payload: dict[str, Any], *, kind: str = "native"+ ) -> dict[str, Any]:+ """Run model/context/tools in Node; service only explicit remaining ports.++ Per-tool calls run concurrently from this turn's ContextVars. Stream+ event calls are acknowledged after publication, providing backpressure.+ Credentials travel only in this private pipe, never process arguments.+ """+ if kind not in {"native", "history", "completion", "service"}:+ raise ValueError("Unknown native engine request")+ await self._ensure_started()+ if len(self._runs) >= _MAX_RUNS:+ raise EngineUnavailableError("TypeScript scheduler is at capacity")+ run_id = uuid.uuid4().hex+ queue: asyncio.Queue[dict[str, Any] | Exception] = asyncio.Queue(maxsize=64)+ self._runs[run_id] = queue+ operations: set[asyncio.Task[None]] = set()++ async def respond(frame: dict[str, Any]) -> None:+ reply = {"kind": "reply", "runId": run_id, "callId": frame["callId"]}+ try:+ reply.update(ok=True, result=await self._invoke_host(host, frame))+ except Exception as exc:+ reply.update(ok=False, error={"message": str(exc)[:4096], "partialResponse": True})+ try:+ await self._send(reply)+ except Exception as exc:+ with suppress(asyncio.QueueFull):+ queue.put_nowait(exc)++ try:+ await self._send({"kind": kind, "runId": run_id, "input": payload})+ while True:+ # Node owns provider idle deadlines; a user/tool wait may be+ # intentionally long. Reader EOF always wakes this queue.+ incoming = asyncio.create_task(queue.get())+ assert self._reader is not None+ try:+ completed, _ = await asyncio.wait(+ (incoming, self._reader), return_when=asyncio.FIRST_COMPLETED+ )+ if incoming not in completed:+ raise EngineUnavailableError("TypeScript engine stopped during turn")+ frame = incoming.result()+ finally:+ if not incoming.done():+ incoming.cancel()+ with suppress(asyncio.CancelledError):+ await incoming+ if isinstance(frame, Exception):+ raise frame+ if frame.get("kind") == "complete":+ return frame["state"]+ if frame.get("kind") == "failed":+ raise EngineUnavailableError(str(frame.get("message") or "Native turn failed"))+ if frame.get("kind") != "call":+ raise EngineUnavailableError("Unknown native engine frame")+ task = asyncio.create_task(respond(frame))+ operations.add(task)+ task.add_done_callback(operations.discard)+ except Exception as exc:+ # A failed native turn may already have visible text or committed+ # tool effects. Never let a partner backup model replay that turn.+ from deeptutor.services.llm.exceptions import LLMProviderTransportError++ raise LLMProviderTransportError(str(exc), partial_response=True) from exc+ finally:+ self._runs.pop(run_id, None)+ for task in operations:+ task.cancel()+ if operations:+ await asyncio.gather(*operations, return_exceptions=True)+ with suppress(Exception, asyncio.CancelledError):+ await self._send({"kind": "cancel", "runId": run_id})+ if not self._runs and not self._closed:+ self._cancel_idle_close()+ self._idle_handle = asyncio.get_running_loop().call_later(+ _IDLE_WORKER_SECONDS, self._schedule_idle_close+ )++ def _cancel_idle_close(self) -> None:+ if self._idle_handle is not None:+ self._idle_handle.cancel()+ self._idle_handle = None++ def _schedule_idle_close(self) -> None:+ self._idle_handle = None+ task = asyncio.create_task(self._close_if_idle())+ task.add_done_callback(+ lambda completed: completed.exception() if not completed.cancelled() else None+ )++ async def _close_if_idle(self) -> None:+ async with self._startup:+ if not self._runs:+ await self._stop_process()++ async def _invoke_host(self, host: Host, frame: dict[str, Any]) -> Any:+ # Spawn from the turn task, never from the shared reader: create_task+ # copies the authenticated/model/workspace context here. Racing the+ # reader also cancels an ask_user/provider wait if the worker dies.+ operation = asyncio.create_task(+ host.invoke(frame["operation"], frame["input"], frame["state"])+ )+ assert self._reader is not None+ try:+ completed, _ = await asyncio.wait(+ (operation, self._reader), return_when=asyncio.FIRST_COMPLETED+ )+ if self._reader in completed:+ raise EngineUnavailableError("TypeScript scheduler stopped during host operation")+ return await operation+ finally:+ if not operation.done():+ operation.cancel()+ with suppress(asyncio.CancelledError):+ await operation++ async def close(self) -> None:+ self._closed = True+ self._cancel_idle_close()+ async with self._startup:+ await self._stop_process()++ async def _stop_process(self) -> None:+ process = self._process+ if process is None:+ return+ if process.returncode is None:+ with suppress(ProcessLookupError):+ process.terminate()+ try:+ await asyncio.wait_for(process.wait(), timeout=3)+ except TimeoutError:+ with suppress(ProcessLookupError):+ process.kill()+ await process.wait()+ if self._reader is not None:+ await self._reader+ self._process = None+++def get_engine_client() -> EngineClient:+ loop = asyncio.get_running_loop()+ # Short-lived Python SDK event loops must not leave Node children behind.+ for old, client in list(_clients.items()):+ if old.is_closed():+ process = client._process+ if process is not None and process.returncode is None:+ with suppress(ProcessLookupError):+ process.terminate()+ _clients.pop(old, None)+ if loop not in _clients:+ _clients[loop] = EngineClient()+ return _clients[loop]+++async def close_engine_clients() -> None:+ client = _clients.pop(asyncio.get_running_loop(), None)+ if client is not None:+ await client.close()+++def _terminate_children() -> None:+ for client in _clients.values():+ process = client._process+ if process is not None and process.returncode is None:+ with suppress(ProcessLookupError):+ process.terminate()diff --cc deeptutor/services/session/_turn_runtime_shared.pyindex ab979d3b0,f7aed022d..396d097da--- a/deeptutor/services/session/_turn_runtime_shared.py+++ b/deeptutor/services/session/_turn_runtime_shared.py@@@ -1338,293 -1496,7 +1338,294 @@@ def _format_followup_question_context(creturn "\n".join(lines).strip()+def _format_side_chat_context(context: dict[str, Any], language: str = "en") -> str:+ if context.get("selected_text"):+ return _format_selection_tutor_context(context, language)+ parent_session_id = str(context.get("parent_session_id") or "").strip() or "(none)"+ messages = context.get("conversation_messages") or []+ zh = str(language or "en").lower().startswith("zh")+ if zh:+ lines = [+ "你是侧栏中的 Dito。学习者在主对话旁边开了一个侧边聊天,想在不打断主对话的前提下追问。",+ "下面的主对话记录是这里所有问题的共同背景;“这个/刚才/上面”默认指主对话里的内容;学习者引用的段落是他们这一问具体指的地方。",+ "优先依据主对话里已有的定义、推导、代码和结论回答;主对话没有提供的信息不要臆造,需要时说明这超出了主对话的范围。",+ "不要读取、引用或写入全局记忆;这里的问答不会写回主对话。",+ "回答要简明、循序渐进。",+ "",+ "[主对话记录(按时间顺序)]",+ ]+ labels = {"user": "学习者", "assistant": "导师", "omitted": "(更早的消息已省略)"}+ else:+ lines = [+ "You are Dito in a sidebar. The learner opened a side chat next to the main conversation to ask follow-up questions without interrupting it.",+ "The main conversation below is the shared background for every question here; 'this', 'that', or 'above' refer to it by default, and a passage the learner quotes is what that question is about.",+ "Ground answers in the definitions, derivations, code, and conclusions the main conversation already has. Do not invent what it does not contain; say so when a question goes beyond it.",+ "Do not read, cite, or write global memory. Nothing said here is written back into the main conversation.",+ "Answer clearly and step by step.",+ "",+ "[Main conversation, oldest first]",+ ]+ labels = {"user": "Learner", "assistant": "Tutor", "omitted": "(earlier messages omitted)"}+ if not messages:+ lines.append("(主对话还没有内容)" if zh else "(the main conversation is still empty)")+ for message in messages:+ role = str(message.get("role") or "")+ if role == "omitted":+ lines.append(labels["omitted"])+ continue+ lines.extend([f"{labels.get(role, role)}:", str(message.get("content") or ""), ""])+ lines.extend(+ ["", f"来源会话:{parent_session_id}" if zh else f"Source session: {parent_session_id}"]+ )+ return "\n".join(lines).strip()+++@dataclass+class _LiveSubscriber:+ queue: asyncio.Queue[dict[str, Any]]+++@dataclass+class _TurnExecution:+ turn_id: str+ session_id: str+ capability: str+ payload: dict[str, Any]+ task: asyncio.Task[None] | None = None+ # True while the turn is parked inside ``ask_user`` waiting for a learner+ # reply. Such a turn holds its resources (notably a mastery path lease)+ # but is doing no work, so another turn may take over from it.+ awaiting_user_reply: bool = False+ subscribers: list[_LiveSubscriber] = field(default_factory=list)+ events: list[dict[str, Any]] = field(default_factory=list)+ next_seq: int = 1+ flush_lock: asyncio.Lock = field(default_factory=asyncio.Lock)++ flush_task: asyncio.Task[None] | None = None+ events_persisted: bool = False+ persisted_events: list[dict[str, Any]] = field(default_factory=list)+ events_flushed: bool = False+ lease: TurnLease | None = None+ coordination_task: asyncio.Task[None] | None = None+ lease_lost: bool = False+ shutdown_requested: bool = False+++# Compatibility for saved requests and clients using passage-based tutoring.+SELECTION_TUTOR_MAX_CHARS = 12_000++def _extract_selection_tutor_context(+ config: dict[str, Any] | None,+) -> dict[str, Any] | None:+ """Remove and normalize context for the Little Tutor side thread.++ Two scopes share the thread: ``selection`` tutors one passage the learner+ selected, ``conversation`` is a side chat about the whole parent+ conversation and needs only that parent.+ """+ if not isinstance(config, dict):+ return None+ raw = config.pop("selection_tutor_context", None)+ if not isinstance(raw, dict):+ return None++ parent_session_id = str(raw.get("parent_session_id", "") or "").strip()+ raw_source_message_id = raw.get("source_message_id")+ source_message_id: int | None = None+ if isinstance(raw_source_message_id, int) and not isinstance(raw_source_message_id, bool):+ source_message_id = raw_source_message_id+ elif str(raw_source_message_id or "").strip().isdigit():+ source_message_id = int(str(raw_source_message_id).strip())++ if str(raw.get("scope", "") or "").strip() == "conversation":+ if not parent_session_id:+ return None+ conversation: dict[str, Any] = {+ "scope": "conversation",+ "selected_text": "",+ "parent_session_id": parent_session_id,+ }+ # The tip of the branch the learner is looking at; edit branches they+ # moved away from are not part of what they are asking about.+ if source_message_id is not None and source_message_id > 0:+ conversation["source_message_id"] = source_message_id+ return conversation++ selected_text = _clip_text(+ str(raw.get("selected_text", "") or "").strip(),+ limit=SELECTION_TUTOR_MAX_CHARS,+ )+ if not selected_text:+ return None+ context: dict[str, Any] = {+ "selected_text": selected_text,+ "parent_session_id": parent_session_id,+ }+ if source_message_id is not None:+ context["source_message_id"] = source_message_id+ source_message_text = str(raw.get("source_message_text", "") or "").strip()+ if source_message_text:+ context["source_message_text"] = source_message_text+ source_message_role = str(raw.get("source_message_role", "") or "").strip()+ if source_message_role in {"user", "assistant", "system"}:+ context["source_message_role"] = source_message_role+ return context++def _selection_source_excerpt(+ source_text: str,+ selected_text: str,+ *,+ limit: int = 12_000,+) -> str:+ """Bound a source message while keeping the selected passage in view."""+ text = str(source_text or "").strip()+ if len(text) <= limit:+ return text++ needle = str(selected_text or "").strip()+ selection_start = _selection_start(text, needle) if needle else -1+ if selection_start < 0:+ return _clip_text(text, limit=limit)++ before = max(1_000, (limit - len(needle)) // 2)+ start = max(0, selection_start - before)+ end = min(len(text), start + limit)+ selection_end = min(len(text), selection_start + max(len(needle), 1))+ if selection_end > end:+ end = selection_end+ start = max(0, end - limit)+ excerpt = text[start:end]+ if start > 0:+ excerpt = "[earlier content omitted]\n" + excerpt+ if end < len(text):+ excerpt += "\n[later content omitted]"+ return excerpt++def _selected_latex_body(selected: str) -> str | None:+ """Return the body of a complete Markdown math selection, if any."""+ match = re.fullmatch(r"\$\$(.+?)\$\$|\$(.+?)\$", selected, flags=re.DOTALL)+ if not match:+ return None+ body = " ".join((match.group(1) or match.group(2) or "").split())+ if not body:+ return None+ # Restrict delimiter equivalence to content that plausibly came from a+ # rendered formula. Ordinary prose selections still require an exact match.+ if not re.search(r"\\[A-Za-z]+|[_^=+*/<>-]", body):+ return None+ return body++def _selection_start(source: str, selected: str) -> int:+ """Find an exact selection, or its equivalent LaTeX body, in source text."""+ start = source.find(selected) if selected else -1+ if start >= 0:+ return start+ body = _selected_latex_body(selected)+ if body is None:+ return -1+ pattern = r"\s+".join(re.escape(part) for part in body.split(" "))+ match = re.search(pattern, source, flags=re.DOTALL)+ return match.start() if match else -1++def _latex_selection_is_grounded(source: str, selected: str) -> bool:+ """Whether selected KaTeX LaTeX has an equivalent body in the source.++ The browser maps a rendered formula back to Markdown ``$...$`` delimiters.+ The authoritative message may instead contain multiline ``$$`` fences,+ bracket/parenthesis delimiters, a code span, or bare LaTeX. Comparing the+ formula body keeps the check content-bound while allowing those display+ representations to differ.+ """+ body = _selected_latex_body(selected)+ if body is None:+ return False+ normalized_source = " ".join(source.split())+ return body in normalized_source++def _selection_is_grounded(source_text: str, selected_text: str) -> bool:+ """Whether the claimed selection occurs in its containing message."""+ source = str(source_text or "")+ selected = str(selected_text or "").strip()+ if not source or not selected:+ return False+ if selected in source:+ return True+ # Browser selections collapse rendered whitespace while the stored source+ # preserves Markdown/code layout. Permit that representational difference,+ # but never accept text that is absent from the authoritative message.+ normalized_source = " ".join(source.split())+ normalized_selected = " ".join(selected.split())+ if normalized_selected and normalized_selected in normalized_source:+ return True+ return _latex_selection_is_grounded(normalized_source, normalized_selected)++async def _resolve_selection_tutor_context(+ store: Any,+ context: dict[str, Any],+) -> dict[str, Any]:+ """Resolve what a Little Tutor thread is grounded in, from its parent chat.++ A selection resolves to its containing message; a side chat resolves to+ the parent conversation itself. Both are read fresh every turn so the+ thread never answers from a stale copy.+ """+ resolved = dict(context)+ parent_session_id = str(resolved.get("parent_session_id") or "").strip()+ if resolved.get("scope") == "conversation":+ leaf = resolved.get("source_message_id")+ try:+ path = await store.get_messages_for_context(+ parent_session_id,+ leaf if isinstance(leaf, int) and leaf > 0 else None,+ )+ except Exception:+ raise ValueError("Could not read the conversation this side chat is about") from None+ resolved["conversation_messages"] = _side_chat_transcript(path)+ return resolved++ source_message_id = resolved.get("source_message_id")++ authoritative_source_required = bool(+ parent_session_id and isinstance(source_message_id, int) and source_message_id > 0+ )+ source_message = None+ if authoritative_source_required:+ try:+ path = await store.get_messages_for_context(+ parent_session_id,+ source_message_id,+ )+ except Exception:+ raise ValueError("Could not resolve the selected text's source message") from None+ else:+ source_message = next(+ (+ message+ for message in reversed(path)+ if str(message.get("id")) == str(source_message_id)+ ),+ None,+ )+ if source_message is None:+ raise ValueError("The selected text's source message was not found")+ resolved["source_message_text"] = str(source_message.get("content") or "").strip()+ role = str(source_message.get("role") or "").strip()+ if role in {"user", "assistant", "system"}:+ resolved["source_message_role"] = role++ source_text = str(resolved.get("source_message_text") or "").strip()+ selected_text = str(resolved.get("selected_text") or "")+ if not _selection_is_grounded(source_text, selected_text):+ qualifier = "authoritative " if authoritative_source_required else ""+ raise ValueError(f"Selected text was not found in the {qualifier}source message")+ resolved["source_message_text"] = _selection_source_excerpt(+ source_text,+ selected_text,+ )+ return resolved+def _format_selection_tutor_context(context: dict[str, Any], language: str = "en") -> str:+ if context.get("scope") == "conversation":+ return _format_side_chat_context(context, language=language)selected_text = context.get("selected_text", "").strip()parent_session_id = context.get("parent_session_id", "").strip() or "(none)"source_message_text = str(context.get("source_message_text") or "").strip()diff --cc deeptutor/services/session/context_builder.pyindex f4dc75d86,b4ab855a7..ba227cb16--- a/deeptutor/services/session/context_builder.py+++ b/deeptutor/services/session/context_builder.py@@@ -2,10 -2,10 +2,11 @@@from __future__ import annotations- from dataclasses import dataclass+ from dataclasses import dataclass, fieldimport jsonimport logging+import os+ import refrom typing import Any, Awaitable, Callablefrom deeptutor.agents.base_agent import BaseAgentdiff --cc deeptutor/services/session/pocketbase_store.pyindex 079b77564,c466bf803..0435d24bb--- a/deeptutor/services/session/pocketbase_store.py+++ b/deeptutor/services/session/pocketbase_store.py@@@ -819,11 -835,12 +835,14 @@@ class PocketBaseSessionStorerecord = _find_session_record(_pb(), sid, uid)if record is None:return False+ current = _json_loads(getattr(record, "preferences_json", None), {})+ if isinstance(current, dict) and _SUMMARY_CURSOR_PREFERENCE_KEY in current:+ merged[_SUMMARY_CURSOR_PREFERENCE_KEY] = current[_SUMMARY_CURSOR_PREFERENCE_KEY]_pb().collection("sessions").update(record.id,- {"preferences_json": merged, "session_updated_at": time.time()},+ {"preferences_json": merged, "session_updated_at": time.time()}+ if touch+ else {"preferences_json": merged},)return Truediff --cc deeptutor/services/session/protocol.pyindex cd0b81d7a,54e1f16ca..658a0f8a3--- a/deeptutor/services/session/protocol.py+++ b/deeptutor/services/session/protocol.py@@@ -247,10 -247,12 +247,12 @@@ class SessionStoreProtocol(SessionRepossession_ids: list[str],) -> list[dict[str, Any]]: ...- async def update_summary(self, session_id: str, summary: str, up_to_msg_id: int) -> bool: ...+ async def update_summary(+ self, session_id: str, summary: str, up_to_msg_id: int | str+ ) -> bool: ...async def update_session_preferences(- self, session_id: str, preferences: dict[str, Any]+ self, session_id: str, preferences: dict[str, Any], *, touch: bool = True) -> bool: ...async def get_session_with_messages(self, session_id: str) -> dict[str, Any] | None: ...diff --cc deeptutor/services/session/sqlite_store.pyindex c13b6a0da,f69e60008..5b4b95338--- a/deeptutor/services/session/sqlite_store.py+++ b/deeptutor/services/session/sqlite_store.py@@@ -3078,11 -3185,11 +3186,11 @@@ class SQLiteSessionStoreconn.commit()return cur.rowcount > 0- async def update_summary(self, session_id: str, summary: str, up_to_msg_id: int) -> bool:- return await self._run(self._update_summary_sync, session_id, summary, up_to_msg_id)+ async def update_summary(self, session_id: str, summary: str, up_to_msg_id: int | str) -> bool:+ return await self._run(self._update_summary_sync, session_id, summary, int(up_to_msg_id))def _update_session_preferences_sync(- self, session_id: str, preferences: dict[str, Any]+ self, session_id: str, preferences: dict[str, Any], touch: bool = True) -> bool:with self._connect() as conn:current = conn.execute(diff --cc packages/chat-engine/src/core/contracts.tsindex da79ad423,000000000..9948d233amode 100644,000000..100644--- a/packages/chat-engine/src/core/contracts.ts+++ b/packages/chat-engine/src/core/contracts.ts@@@ -1,90 -1,0 +1,93 @@@+/** The scheduler owns counters and decisions; ports own effects and conversation data.+ * No provider credentials, prompts, messages or user identity cross the bridge.+ */+export interface LoopConfig {+ explorationBudget: number;+ settlementBudget: number;+ emptyRecoveryBudget: number;+}++export interface LoopState {+ rounds: number;+ exploration_rounds: number;+ settlement_rounds: number;+ tool_steps: number;+ reasoning_budget_recoveries: number;+}++export interface RoundFacts {++ recoveryRejected?: boolean;+ hasTools: boolean;+ hasText: boolean;+ truncated: boolean;+ reasoningBudgetExhausted: boolean;+}++export interface Operations {++ prepare_recovery: { input: Record<string, never>; output: { available: boolean; rejected: boolean } };+ begin_settlement: { input: Record<string, never>; output: null };+ call_round: { input: { settling: boolean; first: boolean }; output: RoundFacts };+ continue_truncated: { input: Record<string, never>; output: null };+ raise_reasoning_budget: { input: Record<string, never>; output: never };+ recover_empty: { input: { force: boolean }; output: null };+ check_finish: { input: Record<string, never>; output: { redirect: boolean; override: boolean } };+ redirect_finish: { input: Record<string, never>; output: null };+ reject_finish: { input: Record<string, never>; output: null };+ finish: { input: { override: boolean }; output: null };+ dispatch_tools: { input: Record<string, never>; output: { pause: boolean } };+ resolve_pause: { input: Record<string, never>; output: boolean };+ after_tools: { input: Record<string, never>; output: { override: boolean; terminate: boolean } };+ terminate: { input: Record<string, never>; output: null };+ forced_finish: { input: { reason: "budget" | "error"; error: string }; output: { extraRounds: number } };+}++export type Operation = keyof Operations;+export interface LoopHost {+ invoke<K extends Operation>(operation: K, input: Operations[K]["input"], state: Readonly<LoopState>): Promise<Operations[K]["output"]>;+}++export class HostFailure extends Error {- constructor(message: string, readonly callId: string, readonly partialResponse: boolean) {++ constructor(message: string, readonly callId: string, readonly partialResponse: boolean, readonly fatal = false) {+ super(message);+ this.name = "HostFailure";+ }+}++export function validateConfig(value: unknown): LoopConfig {+ if (!value || typeof value !== "object") throw new Error("Missing loop config");+ const config = value as Record<string, unknown>;+ for (const key of ["explorationBudget", "settlementBudget", "emptyRecoveryBudget"] as const) {+ const n = config[key];+ if (typeof n !== "number" || !Number.isSafeInteger(n) || n < (key === "settlementBudget" ? 0 : 1) || n > 100_000) {+ throw new Error(`Invalid loop budget: ${key}`);+ }+ }+ return config as unknown as LoopConfig;+}++/** Runtime checks matter at the process boundary; TS types alone disappear. */+export function validateOutput<K extends Operation>(operation: K, value: unknown): Operations[K]["output"] {+ const record = value && typeof value === "object" && !Array.isArray(value)+ ? value as Record<string, unknown> : undefined;+ let fields: string[] | undefined;+ switch (operation) {++ case "prepare_recovery": fields = ["available", "rejected"]; break;+ case "call_round": fields = ["hasTools", "hasText", "truncated", "reasoningBudgetExhausted"]; break;+ case "check_finish": fields = ["redirect", "override"]; break;+ case "dispatch_tools": fields = ["pause"]; break;+ case "after_tools": fields = ["override", "terminate"]; break;+ case "resolve_pause":+ if (typeof value !== "boolean") throw new Error("Invalid pause result");+ break;+ case "forced_finish":+ if (!record || (record.extraRounds !== 0 && record.extraRounds !== 1)) throw new Error("Invalid forced-finish accounting");+ break;+ case "raise_reasoning_budget": throw new Error("Budget exhaustion must terminate with an error");+ default:+ if (value !== null) throw new Error(`Unexpected result for ${operation}`);+ }+ if (fields && (!record || fields.some(key => typeof record[key] !== "boolean"))) {+ throw new Error(`Invalid result for ${operation}`);+ }+ return value as Operations[K]["output"];+}diff --cc packages/chat-engine/src/core/run-loop.tsindex f7ecd4f76,000000000..33564ca76mode 100644,000000..100644--- a/packages/chat-engine/src/core/run-loop.ts+++ b/packages/chat-engine/src/core/run-loop.ts@@@ -1,94 -1,0 +1,111 @@@+import { HostFailure, validateConfig, validateOutput } from "./contracts.js";+import type { LoopConfig, LoopHost, LoopState, Operation, Operations } from "./contracts.js";++/** One scheduler for chat and partner turns, independent of HTTP, storage and providers. */+export async function runLoop(host: LoopHost, input: LoopConfig, signal: AbortSignal): Promise<LoopState> {+ const config = validateConfig(input);+ const state: LoopState = { rounds: 0, exploration_rounds: 0, settlement_rounds: 0, tool_steps: 0, reasoning_budget_recoveries: 0 };+ let settlementStarted = false;+ let emptyRecoveries = 0;+ let finishRedirectUsed = false;++ let recoveryUsed = false;++ const invoke = async <K extends Operation>(operation: K, args: Operations[K]["input"]): Promise<Operations[K]["output"]> => {+ signal.throwIfAborted();+ const result = await host.invoke(operation, args, { ...state });+ signal.throwIfAborted();+ return validateOutput(operation, result);+ };+ const forceFinish = async (reason: "budget" | "error" = "budget", error = "") => {+ const result = await invoke("forced_finish", { reason, error });+ state.rounds += result.extraRounds;+ return state;+ };++ while (true) {+ signal.throwIfAborted();+ const settling = state.exploration_rounds >= config.explorationBudget;+ if (settling) {- if (state.settlement_rounds >= config.settlementBudget) return forceFinish();++ if (state.settlement_rounds >= config.settlementBudget) {++ if (recoveryUsed) {++ await invoke("reject_finish", {});++ return state;++ }++ const recovery = await invoke("prepare_recovery", {});++ if (recovery.rejected) {++ await invoke("reject_finish", {});++ return state;++ }++ if (!recovery.available) return forceFinish();++ recoveryUsed = true;++ }+ if (!settlementStarted) {+ await invoke("begin_settlement", {});+ settlementStarted = true;+ }+ }+ let round;+ try {+ round = await invoke("call_round", { settling, first: state.rounds === 0 });+ } catch (error) {+ // A visible partial response must never be replayed, nor may cancellation+ // be converted into a successful salvage answer.+ signal.throwIfAborted();- if (!(error instanceof HostFailure) || state.rounds === 0 || error.partialResponse) throw error;++ if (!(error instanceof HostFailure) || state.rounds === 0 || error.partialResponse || error.fatal) throw error;+ return forceFinish("error", error.message);+ }+ state.rounds++;+ if (settling) state.settlement_rounds++;+ else state.exploration_rounds++;+++ if (round.recoveryRejected) {++ await invoke("reject_finish", {});++ return state;++ }+ if (!round.hasTools) {+ if (round.truncated || round.reasoningBudgetExhausted) {+ if (round.reasoningBudgetExhausted) {+ if (state.reasoning_budget_recoveries >= 1) await invoke("raise_reasoning_budget", {});+ state.reasoning_budget_recoveries++;+ }+ await invoke("continue_truncated", {});+ continue;+ }+ if (!round.hasText) {+ emptyRecoveries++;+ const force = emptyRecoveries >= config.emptyRecoveryBudget;+ await invoke("recover_empty", { force });+ if (force) return forceFinish();+ continue;+ }+ const decision = await invoke("check_finish", {});+ if (decision.redirect) {+ if (finishRedirectUsed) {+ await invoke("reject_finish", {});+ return state;+ }+ finishRedirectUsed = true;+ await invoke("redirect_finish", {});+ continue;+ }+ await invoke("finish", { override: decision.override });+ return state;+ }++ const dispatch = await invoke("dispatch_tools", {});+ state.tool_steps++;+ if (dispatch.pause) {+ if (await invoke("resolve_pause", {})) continue;+ return state;+ }+ const decision = await invoke("after_tools", {});+ if (decision.override) {+ await invoke("finish", { override: true });+ return state;+ }+ if (decision.terminate) {+ await invoke("terminate", {});+ return state;+ }+ }+}diff --cc packages/chat-engine/src/native/session.tsindex 38f285d61,000000000..15e631c26mode 100644,000000..100644--- a/packages/chat-engine/src/native/session.ts+++ b/packages/chat-engine/src/native/session.ts@@@ -1,407 -1,0 +1,409 @@@+import { HostFailure } from "../core/contracts.js";+import type {+ LoopHost,+ LoopState,+ Operation,+ Operations,+} from "../core/contracts.js";+import { runLoop } from "../core/run-loop.js";+import { Conversation } from "../context/conversation.js";+import { ProviderFailure } from "../providers/chat-completions.js";+import { ToolDispatcher } from "../tools/dispatcher.js";+import { EventCoalescer } from "./event-coalescer.js";+import { modelRound } from "./model-round.js";+import type {+ Dispatch,+ Emit,+ JsonRecord,+ LegacyPort,+ NativeInput,+ NativeResult,+ Round,+ ToolSpec,+} from "./types.js";+import { record, validateNativeInput, validateToolRuntime } from "./types.js";++export class NativeSession implements LoopHost {+ private readonly conversation: Conversation;+ private readonly dispatcher: ToolDispatcher;+ private round: Round | undefined;+ private dispatch: Dispatch | undefined;+ private tools: ToolSpec[];+ private continued: string[] = [];+ private response = "";+ private completed = false;+ private redirect = "";+ private override: string | null = null;+ private sources: JsonRecord[] = [];+ private usage: JsonRecord[] = [];+ private refreshHost = false;+ private state: LoopState = {+ rounds: 0,+ exploration_rounds: 0,+ settlement_rounds: 0,+ tool_steps: 0,+ reasoning_budget_recoveries: 0,+ };+ constructor(+ readonly input: NativeInput,+ readonly legacy: LegacyPort,+ readonly emit: Emit,+ readonly signal: AbortSignal,+ ) {+ this.conversation = new Conversation(input.seed);+ this.tools = input.tools;+ this.dispatcher = new ToolDispatcher(+ input,+ legacy,+ emit,+ signal,+ async (call, output) => {+ this.conversation.resolveTool(call.id, output.content);+ await this.checkpoint();+ },+ );+ }+ async run(): Promise<NativeResult> {+ await this.checkpoint();+ this.state = await runLoop(this, this.input.config, this.signal);+ await this.checkpoint();+ return {+ state: this.state,+ response: this.response,+ completed: this.completed,+ sources: this.sources,+ contextBudget: this.conversation.budget(),+ usage: this.usage,+ nativeToolCalls: this.dispatcher.nativeCalls,+ legacyToolCalls: this.dispatcher.legacyCalls,+ };+ }+ async invoke<K extends Operation>(+ operation: K,+ args: Operations[K]["input"],+ state: Readonly<LoopState>,+ ): Promise<Operations[K]["output"]> {+ this.state = { ...state };+ return (await this.operate(operation, args)) as Operations[K]["output"];+ }+ private async checkpoint(): Promise<void> {+ await this.legacy("checkpoint", {+ modelTurn: this.conversation.checkpoint(),+ });+ }+ private async warning(key: string, fallback: string): Promise<void> {+ await this.emit({+ type: "progress",+ content: this.input.copy[key] || fallback,+ metadata: { trace_kind: "warning" },+ });+ }+ private async release(discard = false): Promise<void> {+ if (!this.round) return;+ if (discard) {+ this.round.deferred.length = 0;+ await this.emit({+ type: "progress",+ content: "",+ metadata: { ...this.round.trace, answer_visible: false },+ });+ } else+ for (const event of this.round.deferred.splice(0)) await this.emit(event);+ }+ private async call(+ settling: boolean,+ first: boolean,+ tools = this.tools,+ ): Promise<Round> {+ try {+ const round = await modelRound(+ this.input,+ this.conversation,+ tools.map((s) => s.schema),+ this.emit,+ this.signal,+ settling,+ first,+ );+ this.usage.push(round.usage);+ return round;+ } catch (error) {+ if (error instanceof ProviderFailure)+ throw new HostFailure(+ error.message,+ "native-provider",+ error.partialResponse,+ );+ throw error;+ }+ }+ private async policy(+ text: string,+ tools: string[] = [],+ ): Promise<JsonRecord> {+ if (!this.input.policyHooks)+ return { redirect: "", override: null, toolPolicy: "keep" };+ return record(await this.legacy("policy", { text, tools }));+ }+ private async finish(override: boolean): Promise<void> {+ if (!this.round) throw new Error("Missing model round");+ const text = override ? (this.override ?? "") : this.round.text.trim();+ if (override) {+ await this.release(true);+ await this.legacy("publish_override", { text });+ this.conversation.messages.push({ role: "assistant", content: text });+ } else {+ await this.release();+ this.conversation.appendAssistant(this.round);+ }+ this.response = [...this.continued, text].filter(Boolean).join("\n\n");+ this.completed = true;+ }+ private async operate(+ operation: Operation,+ args: JsonRecord,+ ): Promise<unknown> {+ switch (operation) {++ case "prepare_recovery":++ return { available: false, rejected: false };+ case "begin_settlement":+ await this.warning(+ "budget_settling",+ "Exploration budget reached; settling the current task.",+ );+ this.conversation.appendInstruction(+ this.input.copy.settle ||+ "Finish the work already started. Use only the tools needed to settle the current task, then answer.",+ );+ return null;+ case "call_round": {+ if (this.input.userInputEnabled) {+ const raw = await this.legacy("read_user_inputs", {});+ const inputs = Array.isArray(raw) ? raw.map(record) : [];+ if (inputs.length) {+ const lead =+ this.input.copy.user_sent_while_working ||+ "[The user sent this while you were working. Take it into account from here on.]";+ this.conversation.appendInstruction(+ `${lead}\n${inputs.map((item) => String(item.content || "")).join("\n\n")}`,+ );+ await this.emit({+ type: "progress",+ content: "",+ metadata: {+ trace_kind: "user_input",+ user_inputs: inputs,+ },+ });+ await this.checkpoint();+ }+ }+ this.round = await this.call(+ args.settling === true,+ args.first === true,+ );+ const truncated = [+ "length",+ "max_tokens",+ "max_output_tokens",+ ].includes(this.round.finishReason);+ return {+ hasTools: this.round.toolCalls.length > 0,+ hasText: !!this.round.text.trim(),+ truncated,+ reasoningBudgetExhausted:+ truncated &&+ !this.round.text.trim() &&+ !!this.round.reasoning &&+ !this.round.toolCalls.length,+ };+ }+ case "continue_truncated":+ if (!this.round) throw new Error("Missing truncated round");+ await this.release();+ this.conversation.appendAssistant(this.round);+ if (this.round.text) this.continued.push(this.round.text);+ this.conversation.appendInstruction(+ this.round.text+ ? this.input.copy.continue_truncated ||+ "Continue where the response stopped, without repetition, and finish the answer."+ : this.input.copy.continue_reasoning ||+ "Your output budget was spent on reasoning. Act now: call a tool or write the answer without reconsidering the plan.",+ );+ await this.warning(+ "output_truncated",+ "The model reached its output limit; continuing.",+ );+ await this.checkpoint();+ return null;+ case "raise_reasoning_budget":+ throw new Error(+ "The model exhausted its reasoning output budget twice without an answer",+ );+ case "recover_empty":+ if (this.round?.reasoning)+ this.conversation.appendAssistant(this.round);+ this.conversation.appendInstruction(+ this.input.copy.empty_nudge ||+ "Your last round produced no answer or tool action. Execute a tool or write the answer now.",+ );+ return null;+ case "check_finish": {+ const policy = await this.policy(this.round?.text.trim() || "");+ this.redirect = String(policy.redirect || "");+ this.override =+ typeof policy.override === "string" ? policy.override : null;+ if (this.redirect) await this.release(true);+ return { redirect: !!this.redirect, override: this.override !== null };+ }+ case "redirect_finish":+ if (this.round) this.conversation.appendAssistant(this.round);+ this.conversation.appendInstruction(this.redirect);+ return null;+ case "reject_finish":+ await this.warning(+ "finish_rejected",+ "The required capability action was not completed.",+ );+ this.completed = false;+ return null;+ case "finish":+ await this.finish(args.override === true);+ return null;+ case "dispatch_tools": {+ if (!this.round) throw new Error("Missing tool round");+ const policy = await this.policy(+ this.round.text,+ this.round.toolCalls.map((c) => c.name),+ );+ await this.release(policy.toolPolicy === "discard");+ this.conversation.appendAssistant(this.round);+ this.conversation.beginTools(this.round.toolCalls);+ await this.checkpoint();+ const previousLegacyCalls = this.dispatcher.legacyCalls;+ this.dispatch = await this.dispatcher.run(+ this.round.toolCalls,+ this.tools,+ this.state.tool_steps,+ ["length", "max_tokens", "max_output_tokens"].includes(+ this.round.finishReason,+ )+ ? "Model output was truncated. No tools in this batch were executed; retry with complete arguments."+ : "",+ );+ this.refreshHost =+ this.input.policyHooks ||+ this.dispatcher.legacyCalls !== previousLegacyCalls;+ this.usage.push(...(this.dispatch.usage || []));+ this.sources.push(...this.dispatch.sources);+ this.conversation.appendTools([], this.dispatch.modelMessages);+ await this.checkpoint();+ return { pause: this.dispatch.pause !== null };+ }+ case "resolve_pause": {+ if (!this.dispatch?.pause) throw new Error("Missing pause");+ const reply = record(+ await this.legacy("wait_for_reply", { dispatch: this.dispatch }),+ );+ if (reply.resumed === true && typeof reply.content === "string")+ this.conversation.resolveTool(+ this.dispatch.pause.callId,+ reply.content,+ );+ await this.checkpoint();+ return reply.resumed === true;+ }+ case "after_tools": {+ if (!this.refreshHost)+ return { override: false, terminate: !!this.dispatch?.terminate };+ const update = record(+ await this.legacy("after_tools", {+ metadataById: this.dispatch?.metadataById || {},+ }),+ );+ if (Array.isArray(update.tools))+ this.tools = update.tools as ToolSpec[];+ if (update.toolRuntime)+ this.input.toolRuntime = validateToolRuntime(update.toolRuntime);+ if (typeof update.checkpoint === "string" && update.checkpoint)+ this.conversation.foldCheckpoint(update.checkpoint);+ this.override =+ typeof update.override === "string" ? update.override : null;+ return {+ override: this.override !== null,+ terminate: !!this.dispatch?.terminate,+ };+ }+ case "terminate": {+ const value = this.dispatch?.terminate;+ if (!value) throw new Error("Missing terminal tool");+ await this.legacy("publish_terminator", { value });+ this.response = [...this.continued, value.content]+ .filter(Boolean)+ .join("\n\n");+ this.completed = true;+ this.conversation.messages.push({+ role: "assistant",+ content: this.response,+ });+ return null;+ }+ case "forced_finish": {+ this.conversation.appendInstruction(+ this.input.copy.finish ||+ "The tool budget is exhausted. Write the final answer using available evidence; do not call tools.",+ );+ this.round = await this.call(true, false, []);+ if (this.round.toolCalls.length)+ throw new Error(+ "Provider emitted tools after tool execution was disabled",+ );+ if (!this.round.text.trim())+ throw new Error("Model returned an empty final answer");+ if (+ ["length", "max_tokens", "max_output_tokens"].includes(+ this.round.finishReason,+ )+ )+ throw new Error("Final answer exceeded the output budget");+ const policy = await this.policy(this.round.text);+ if (policy.redirect) {+ await this.release(true);+ this.completed = false;+ return { extraRounds: 1 };+ }+ this.override =+ typeof policy.override === "string" ? policy.override : null;+ await this.finish(this.override !== null);+ return { extraRounds: 1 };+ }+ }+ }+}++export async function runNative(+ value: unknown,+ legacy: LegacyPort,+ signal: AbortSignal,+): Promise<NativeResult> {+ const input = validateNativeInput(value);+ const events = new EventCoalescer(async (event) => {+ await legacy("event", { event });+ });+ try {+ const result = await new NativeSession(+ input,+ legacy,+ events.emit,+ signal,+ ).run();+ await events.flush();+ return result;+ } catch (error) {+ // Do not mask the original provider/cancellation failure with a closed host.+ if (!signal.aborted) await events.flush().catch(() => {});+ throw error;+ } finally {+ events.discard();+ }+}diff --cc packages/chat-engine/src/transport/stdio.tsindex 74c0ee848,000000000..9724374e2mode 100644,000000..100644--- a/packages/chat-engine/src/transport/stdio.ts+++ b/packages/chat-engine/src/transport/stdio.ts@@@ -1,205 -1,0 +1,206 @@@+/** Private, versioned parent/child transport. stdout is exclusively protocol. */+import { createInterface } from "node:readline";+import { once } from "node:events";+import { runLoop } from "../core/run-loop.js";+import { HostFailure, validateConfig } from "../core/contracts.js";+import type {+ LoopHost,+ LoopState,+ Operation,+ Operations,+} from "../core/contracts.js";++type Pending = {+ resolve: (value: unknown) => void;+ reject: (error: Error) => void;+};+type Run = {+ controller: AbortController;+ pending: Map<string, Pending>;+ next: number;+};+const runs = new Map<string, Run>();+const MAX_RUNS = 128;+const MAX_LINE = 48 * 1024 * 1024;+let writing = Promise.resolve();++async function send(message: object): Promise<void> {+ const frame = JSON.stringify({ v: 1, ...message }) + "\n";+ if (Buffer.byteLength(frame) > MAX_LINE)+ throw new Error("Engine frame exceeds limit");+ // Serialize writes, honoring backpressure without interleaving JSON lines.+ writing = writing.then(async () => {+ if (!process.stdout.write(frame)) await once(process.stdout, "drain");+ });+ return writing;+}++function abort(run: Run): void {+ run.controller.abort();+ for (const pending of run.pending.values())+ pending.reject(new Error("Turn cancelled"));+ run.pending.clear();+}++async function execute(+ id: string,+ config: unknown,+ mode: "run" | "native" | "history" | "completion" | "service" = "run",+): Promise<void> {+ if (runs.has(id) || runs.size >= MAX_RUNS) {+ await send({+ kind: "failed",+ runId: id,+ message: "Chat engine capacity or duplicate run",+ });+ return;+ }+ const run: Run = {+ controller: new AbortController(),+ pending: new Map(),+ next: 0,+ };+ runs.set(id, run);+ const host: LoopHost = {+ async invoke<K extends Operation>(+ operation: K,+ input: Operations[K]["input"],+ state: Readonly<LoopState>,+ ): Promise<Operations[K]["output"]> {+ const callId = String(++run.next);+ const response = new Promise<unknown>((resolve, reject) => {+ run.pending.set(callId, { resolve, reject });+ });+ // Attach the handler before a broken pipe or cancellation can reject it.+ const sent = send({+ kind: "call",+ runId: id,+ callId,+ operation,+ input,+ state,+ });+ const [, result] = await Promise.all([sent, response]);+ return result as Operations[K]["output"];+ },+ };+ try {+ const port = (operation: string, input: Record<string, unknown>) =>+ host.invoke(operation as Operation, input as never, {+ rounds: 0,+ exploration_rounds: 0,+ settlement_rounds: 0,+ tool_steps: 0,+ reasoning_budget_recoveries: 0,+ });+ const state =+ mode === "native"+ ? await (+ await import("../native/session.js")+ ).runNative(config, port, run.controller.signal)+ : mode === "history"+ ? await (+ await import("../context/history.js")+ ).planHistory(+ config as import("../context/history.js").HistoryInput,+ port,+ run.controller.signal,+ )+ : mode === "service"+ ? await (+ await import("../providers/service-call.js")+ ).serviceCall(config, port, run.controller.signal)+ : mode === "completion"+ ? await (+ await import("../providers/one-shot.js")+ ).oneShot(+ config as Parameters<+ typeof import("../providers/one-shot.js").oneShot+ >[0],+ run.controller.signal,+ )+ : await runLoop(+ host,+ validateConfig(config),+ run.controller.signal,+ );+ await send({ kind: "complete", runId: id, state });+ } catch (error) {+ if (!run.controller.signal.aborted) {+ await send({+ kind: "failed",+ runId: id,+ callId: error instanceof HostFailure ? error.callId : undefined,+ partialResponse:+ mode !== "run" ||+ (error instanceof HostFailure && error.partialResponse),+ message: error instanceof Error ? error.message : "Engine failed",+ });+ }+ } finally {+ abort(run);+ runs.delete(id);+ }+}++const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });+lines.on("line", (line: string) => {+ try {+ if (Buffer.byteLength(line) > MAX_LINE)+ throw new Error("Oversized engine frame");+ const frame: unknown = JSON.parse(line);+ if (!frame || typeof frame !== "object")+ throw new Error("Invalid engine frame");+ const value = frame as Record<string, unknown>;+ if (+ value.v !== 1 ||+ typeof value.runId !== "string" ||+ value.runId.length > 128+ )+ throw new Error("Invalid engine protocol");+ const run = runs.get(value.runId);+ if (value.kind === "run") void execute(value.runId, value.config);+ else if (+ value.kind === "native" ||+ value.kind === "history" ||+ value.kind === "completion" ||+ value.kind === "service"+ )+ void execute(value.runId, value.input, value.kind);+ else if (value.kind === "cancel") {+ if (run) abort(run);+ } else if (value.kind === "reply") {+ if (typeof value.callId !== "string")+ throw new Error("Invalid call identity");+ const pending = run?.pending.get(value.callId);+ if (!pending) return; // Late reply to a cancelled run.+ run?.pending.delete(value.callId);+ if (value.ok === true) pending.resolve(value.result);+ else {+ const error = value.error as Record<string, unknown> | undefined;+ pending.reject(+ new HostFailure(+ String(error?.message ?? "Host operation failed"),+ value.callId,+ error?.partialResponse === true,++ error?.fatal === true,+ ),+ );+ }+ } else throw new Error("Unknown engine frame");+ } catch {+ // Malformed internal protocol is fatal, never silently replay a turn.+ process.stderr.write("Invalid chat engine protocol frame\n");+ for (const run of runs.values()) abort(run);+ process.exitCode = 1;+ lines.close();+ process.stdin.destroy();+ }+});+lines.on("close", () => {+ for (const run of runs.values()) abort(run);+});+process.stdout.on("error", () => {+ for (const run of runs.values()) abort(run);+ process.exit(1);+});diff --cc packages/chat-engine/test/run-loop.test.tsindex 7a1795483,000000000..75d2b7f49mode 100644,000000..100644--- a/packages/chat-engine/test/run-loop.test.ts+++ b/packages/chat-engine/test/run-loop.test.ts@@@ -1,160 -1,0 +1,189 @@@+import { test } from "node:test";+import assert from "node:assert/strict";+import { runLoop } from "../src/core/run-loop.js";+import { HostFailure } from "../src/core/contracts.js";+import type { LoopConfig, LoopHost, LoopState, Operation, Operations, RoundFacts } from "../src/core/contracts.js";++const answer: RoundFacts = { hasTools: false, hasText: true, truncated: false, reasoningBudgetExhausted: false };+const tools: RoundFacts = { ...answer, hasTools: true };+const empty: RoundFacts = { ...answer, hasText: false };+const config: LoopConfig = { explorationBudget: 2, settlementBudget: 3, emptyRecoveryBudget: 2 };++class Script implements LoopHost {+ calls: Array<{ operation: Operation; input: unknown; state: Readonly<LoopState> }> = [];++ recovery = false;+ redirect = false;+ override = false;+ pause = false;+ resumed = true;+ terminate = false;+ controller = new AbortController();+ cancelAt: Operation | undefined;+ constructor(readonly rounds: Array<RoundFacts | Error>) {}+ async invoke<K extends Operation>(operation: K, input: Operations[K]["input"], state: Readonly<LoopState>): Promise<Operations[K]["output"]> {+ this.calls.push({ operation, input, state });+ if (operation === this.cancelAt) this.controller.abort();+ let result: unknown = null;+ switch (operation) {+ case "call_round": {+ const round = this.rounds.shift();+ if (round instanceof Error) throw round;+ if (!round) throw new Error("Unexpected model call");+ result = round;+ break;+ }++ case "prepare_recovery": result = { available: this.recovery, rejected: false }; break;+ case "check_finish": result = { redirect: this.redirect, override: this.override }; break;+ case "dispatch_tools": result = { pause: this.pause }; break;+ case "resolve_pause": result = this.resumed; break;+ case "after_tools": result = { override: this.override, terminate: this.terminate }; break;+ case "forced_finish": result = { extraRounds: 1 }; break;+ case "raise_reasoning_budget": throw new HostFailure("reasoning budget", "budget", false);+ }+ return result as Operations[K]["output"];+ }+ run(override: Partial<LoopConfig> = {}) { return runLoop(this, { ...config, ...override }, this.controller.signal); }+ operations() { return this.calls.map(c => c.operation); }+}++test("plain answer takes one round and does not invoke tools", async () => {+ const host = new Script([answer]);+ assert.equal((await host.run()).rounds, 1);+ assert.deepEqual(host.operations(), ["call_round", "check_finish", "finish"]);+});++test("tools finish before the next model call and own an independent step counter", async () => {+ const host = new Script([tools, answer]);+ const state = await host.run();+ assert.equal(state.tool_steps, 1);+ assert.equal(state.rounds, 2);+ assert.deepEqual(host.operations(), ["call_round", "dispatch_tools", "after_tools", "call_round", "check_finish", "finish"]);+});++test("budget allows bounded settlement then exactly one tool-less hard finish", async () => {+ const host = new Script(Array.from({ length: 5 }, () => tools));+ assert.deepEqual(await host.run(), { rounds: 6, exploration_rounds: 2, settlement_rounds: 3, tool_steps: 5, reasoning_budget_recoveries: 0 });+ assert.equal(host.operations().filter(x => x === "begin_settlement").length, 1);+ assert.equal(host.operations().at(-1), "forced_finish");+});++test("zero settlement budget immediately hard-finishes after exploration", async () => {+ const host = new Script([tools]);+ assert.equal((await host.run({ explorationBudget: 1, settlementBudget: 0 })).rounds, 2);+ assert.ok(!host.operations().includes("begin_settlement"));+});++test("pause resumes in protocol without folding a checkpoint early", async () => {+ const host = new Script([tools, answer]); host.pause = true;+ await host.run();+ assert.deepEqual(host.operations(), ["call_round", "dispatch_tools", "resolve_pause", "call_round", "check_finish", "finish"]);+});++test("unresolved pause returns without finalizing or spending another round", async () => {+ const host = new Script([tools]); host.pause = true; host.resumed = false;+ assert.equal((await host.run()).rounds, 1);+ assert.equal(host.operations().at(-1), "resolve_pause");+});++test("truncated answer continues under the same total round budget", async () => {+ const host = new Script([{ ...answer, truncated: true }, answer]);+ assert.equal((await host.run()).rounds, 2);+ assert.equal(host.operations()[1], "continue_truncated");+});++test("repeated reasoning budget exhaustion raises instead of empty success", async () => {+ const exhausted = { ...empty, reasoningBudgetExhausted: true };+ const host = new Script([exhausted, exhausted]);+ await assert.rejects(host.run(), /reasoning budget/);+ assert.ok(!host.operations().includes("finish"));+ assert.ok(!host.operations().includes("forced_finish"));+});++test("two empty rounds force a final response", async () => {+ const host = new Script([empty, empty]);+ assert.equal((await host.run()).rounds, 3);+ assert.equal(host.operations().at(-1), "forced_finish");+});++test("capability guard redirects once then rejects", async () => {+ const host = new Script([answer, answer]); host.redirect = true;+ await host.run();+ assert.equal(host.operations().filter(x => x === "redirect_finish").length, 1);+ assert.equal(host.operations().at(-1), "reject_finish");+});++test("capability override precedes a terminator after tools", async () => {+ const host = new Script([tools]); host.override = true; host.terminate = true;+ await host.run();+ assert.equal(host.operations().at(-1), "finish");+ assert.deepEqual(host.calls.at(-1)?.input, { override: true });+});++test("terminator does not ask the model for another response", async () => {+ const host = new Script([tools]); host.terminate = true;+ await host.run();+ assert.equal(host.operations().at(-1), "terminate");+});++test("first-round provider errors preserve failure", async () => {+ const error = new HostFailure("provider unavailable", "1", false);+ const host = new Script([error]);+ await assert.rejects(host.run(), e => e === error);+ assert.deepEqual(host.operations(), ["call_round"]);+});++test("later error can salvage completed work", async () => {+ const host = new Script([tools, new HostFailure("provider unavailable", "2", false)]);+ assert.equal((await host.run()).rounds, 2);+ assert.deepEqual(host.calls.at(-1)?.input, { reason: "error", error: "provider unavailable" });+});++test("partial visible output never triggers an implicit retry", async () => {+ const error = new HostFailure("partial", "2", true);+ const host = new Script([tools, error]);+ await assert.rejects(host.run(), e => e === error);+ assert.ok(!host.operations().includes("forced_finish"));+});++for (const operation of ["call_round", "dispatch_tools", "resolve_pause"] as const) {+ test(`cancellation during ${operation} never starts another effect`, async () => {+ const host = new Script([tools, answer]); host.pause = true; host.cancelAt = operation;+ await assert.rejects(host.run(), { name: "AbortError" });+ assert.equal(host.operations().at(-1), operation);+ });+}++test("invalid budgets are rejected before invoking any effect", async () => {+ for (const explorationBudget of [0, -1, Infinity, NaN, 1.5, 100_001]) {+ const host = new Script([answer]);+ await assert.rejects(host.run({ explorationBudget }), /Invalid loop budget/);+ assert.deepEqual(host.calls, []);+ }+});++++++test("source recovery gets one restricted delivery round within the hard budget", async () => {++ const host = new Script([tools, tools, answer]);++ host.recovery = true;++ assert.equal((await host.run({ explorationBudget: 1, settlementBudget: 1 })).rounds, 3);++ assert.equal(host.operations().at(-1), "finish");++ assert.ok(!host.operations().includes("forced_finish"));++});++++test("recovery cannot reopen exploration or dispatch a rejected tool batch", async () => {++ for (const rejected of [false, true]) {++ const host = new Script([tools, tools, { ...tools, recoveryRejected: rejected }]);++ host.recovery = true;++ const state = await host.run({ explorationBudget: 1, settlementBudget: 1 });++ assert.equal(state.rounds, 3);++ assert.equal(state.tool_steps, rejected ? 2 : 3);++ assert.equal(host.operations().at(-1), "reject_finish");++ assert.ok(!host.operations().includes("forced_finish"));++ }++});++++test("failed capability prerequisites propagate without a salvage call", async () => {++ const host = new Script([tools, new HostFailure("source unavailable", "prerequisite", false, true)]);++ await assert.rejects(host.run(), /source unavailable/);++ assert.ok(!host.operations().includes("forced_finish"));++});diff --cc pyproject.tomlindex c8fdedc96,3b68bbca5..aa03da8d9--- a/pyproject.toml+++ b/pyproject.toml@@@ -87,11 -93,9 +93,10 @@@ dependencies ="loguru>=0.7.3,<1.0.0","json-repair>=0.57.0,<1.0.0","croniter>=6.0.0,<7.0.0",+ "python-dateutil>=2.9.0,<3.0.0",- # Process-tree memory readings for /api/system/memory. Soft dependency:- # deeptutor.runtime.memory_probe imports it lazily and falls back to /proc,- # so a missing wheel costs the settings strip, not the app.+ # Process-tree memory readings and Windows MinerU worker ownership."psutil>=5.9.0,<8.0.0",+ "pywin32; sys_platform == 'win32'", # MinerU Job Object ownership][project.scripts]diff --cc tests/multi_user/test_learning_policy_http.pyindex 154267ede,7f8eaee95..684f786f3--- a/tests/multi_user/test_learning_policy_http.py+++ b/tests/multi_user/test_learning_policy_http.py@@@ -224,14 -224,90 +224,103 @@@ def test_dashboard_learning_library_folassert "reading surface" in denied.json()["detail"]+def test_learning_navigation_index_filters_sources_without_opening_dashboard(learner_client, as_user):+ client, learner, current_user, tmp_path = learner_client+ with as_user(current_user.id, username="student"):+ material = _seed_material(tmp_path, "navigation.txt", "Assigned reading.")+ _save_learner_grant(learner["id"], material.material_id, allowed_surfaces=["reading"])++ response = client.get("/api/dashboard/learning-index")+ assert response.status_code == 200, response.text+ sources = response.json()["sources"]+ assert sources["books"] == sources["mastery"] == sources["practice"] == []+ assert client.get("/api/dashboard/overview").status_code == 403+++++ @pytest.mark.parametrize(+ "surfaces", [["reading"], ["chat"], ["books"], ["books", "chat", "reading"]]+ )+ def test_learning_home_only_reads_granted_surfaces(learner_client, monkeypatch, surfaces):+ """#1987: the aggregate page works without opening a denied source reader."""+ from deeptutor.api.routers import book, mastery_path+ from deeptutor.services.session import organization++ client, learner, _current_user, _tmp_path = learner_client+ _save_learner_grant(learner["id"], "assigned", allowed_surfaces=surfaces)+ calls = []++ async def books():+ calls.append("books")+ return {"books": [{"id": "book"}]}++ async def mastery():+ calls.append("chat")+ return {"topics": [{"id": "topic"}]}++ async def collections(**_kwargs):+ calls.append("reading")+ return {"workspaces": [{"id": "collection"}]}++ async def watching(_store):+ calls.append("reading")+ return [{"id": "video", "preferences": {"workspace_mode": "immersive_watching"}}]++ monkeypatch.setattr(book, "list_books", books)+ monkeypatch.setattr(mastery_path, "list_topics", mastery)+ monkeypatch.setattr(reading, "list_workspaces", collections)+ monkeypatch.setattr(organization, "list_all_sessions_snapshot", watching)+ monkeypatch.setattr(dashboard, "get_session_store", lambda: object())++ response = client.get("/api/dashboard/learning-index")+ assert response.status_code == 200, response.text+ assert response.json()["failed"] == []+ for kind, surface in {+ "books": "books",+ "mastery": "chat",+ "reading": "reading",+ "watching": "reading",+ }.items():+ assert bool(response.json()["sources"][kind]) == (surface in surfaces)+ assert set(calls) == set(surfaces)+ assert client.get("/api/dashboard/recent").status_code == 403+ assert client.get("/api/dashboard/source-library/chats").status_code == 403+ assert client.get("/api/dashboard/learning-index-private").status_code == 403+++ def test_learning_home_retains_assigned_material_filtering(learner_client, as_user):+ from deeptutor.reading.catalog_store import ReadingCatalogStore++ client, learner, current_user, tmp_path = learner_client+ with as_user(current_user.id, username="student"):+ allowed = _seed_material(tmp_path, "home-allowed.txt", "Assigned passage.")+ private = _seed_material(tmp_path, "home-private.txt", "Unassigned passage.")+ catalog = ReadingCatalogStore()+ catalog.register_manifest(allowed)+ catalog.register_manifest(private)+ workspace = catalog.create_workspace("Mixed", [allowed.material_id, private.material_id])+ _save_learner_grant(learner["id"], allowed.material_id, allowed_surfaces=["reading"])++ response = client.get("/api/dashboard/learning-index")+ assert response.status_code == 200, response.text+ rows = response.json()["sources"]["reading"]+ assert [row["workspace_id"] for row in rows] == [workspace.workspace_id]+ assert [tab["material"]["material_id"] for tab in rows[0]["tabs"]] == [allowed.material_id]+ assert private.material_id not in response.text+++ @pytest.mark.parametrize("surfaces,expected", [(["chat"], 200), (["reading"], 403)])+ def test_mastery_library_obeys_chat_surface(learner_client, monkeypatch, surfaces, expected):+ from deeptutor.api.routers import mastery_path++ client, learner, _current_user, _tmp_path = learner_client+ _save_learner_grant(learner["id"], "assigned", allowed_surfaces=surfaces)+ calls = []++ async def topics():+ calls.append(True)+ return {"topics": [{"id": "topic"}]}++ monkeypatch.setattr(mastery_path, "list_topics", topics)+ response = client.get("/api/dashboard/learning-library/mastery")+ assert response.status_code == expected, response.text+ assert bool(calls) == (expected == 200)diff --cc tests/runtime/coordination/test_memory_coordinator.pyindex 73d942ce5,2705b8cda..540a46819--- a/tests/runtime/coordination/test_memory_coordinator.py+++ b/tests/runtime/coordination/test_memory_coordinator.py@@@ -135,60 -135,19 +135,78 @@@ async def test_background_leader_is_sinassert successor.fencing_token > leader.fencing_token+async def test_a_released_turn_tail_is_dropped_after_its_retention(monkeypatch) -> None:+ """The durable journal holds a finished turn; the live tail is a bridge+ and must not outlive the process's interest in it."""+ coordinator = MemoryCoordinator()+ coordinator.retention_seconds = 0.0+ lease = await coordinator.acquire_turn("turn-a", "session-1", "worker-a")+ assert lease is not None+ for index in range(3):+ await coordinator.publish_event("turn-a", {"type": "content", "content": str(index)})+ await coordinator.submit_command("turn-a", "cancel", {}, command_id="cancel-1")++ # Still live: nothing is dropped while the lease is held.+ assert len(await coordinator.read_events("turn-a")) == 3++ await coordinator.release_turn(lease)+ assert await coordinator.read_events("turn-a") == []+ assert await coordinator.read_commands("turn-a") == []+ assert coordinator._events == {} and coordinator._commands == {}+ assert coordinator._command_ids == {}+++async def test_a_late_write_for_an_unleased_turn_still_expires() -> None:+ coordinator = MemoryCoordinator()+ coordinator.retention_seconds = 0.0+ await coordinator.publish_event("turn-late", {"type": "session_meta"})+ assert await coordinator.read_events("turn-late") == []+++async def test_replays_and_reads_use_the_sequence_not_a_scan() -> None:+ coordinator = MemoryCoordinator()+ published = [+ await coordinator.publish_event("turn-a", {"type": "content", "content": str(i)})+ for i in range(50)+ ]+ assert await coordinator.publish_event("turn-a", dict(published[17])) == published[17]+ with pytest.raises(ValueError, match="conflict"):+ await coordinator.publish_event("turn-a", {"seq": 18, "type": "content", "content": "x"})+ tail = await coordinator.read_events("turn-a", 45)+ assert [row["seq"] for row in tail] == [46, 47, 48, 49, 50]+++async def test_acknowledged_background_commands_are_released() -> None:+ coordinator = MemoryCoordinator()+ for index in range(3):+ await coordinator.submit_background_command("cron_reload", command_id=f"reload-{index}")+ rows = await coordinator.read_background_commands()+ await coordinator.acknowledge_background_command(rows[1][0])++ assert [command.command_id for _, command in coordinator._background_commands] == ["reload-2"]+ later = await coordinator.submit_background_command("cron_reload", command_id="reload-3")+ assert later is not None+ # Numbering keeps counting after the list was trimmed.+ assert [cursor for cursor, _ in await coordinator.read_background_commands()] == ["3-0", "4-0"]+++++ @pytest.mark.asyncio+ async def test_acknowledged_turn_releases_payloads_but_live_owner_keeps_them() -> None:+ coordinator = MemoryCoordinator()+ lease = await coordinator.acquire_turn("turn-a", "session-a", "worker")+ assert lease is not None+ await coordinator.publish_event("turn-a", {"type": "content", "content": "large answer"})+ await coordinator.submit_command("turn-a", "cancel", command_id="cancel-a")+ await coordinator.acknowledge_expired_turn("turn-a")+ assert len(await coordinator.read_events("turn-a")) == 1+ assert len(await coordinator.read_commands("turn-a")) == 1+ await coordinator.release_turn(lease)+ await coordinator.acknowledge_expired_turn("turn-a")+ assert await coordinator.read_events("turn-a") == []+ assert await coordinator.read_commands("turn-a") == []+ assert "cancel-a" not in coordinator._command_ids+ assert await coordinator.list_expired_turn_ids() == []diff --cc tests/runtime/test_ts_engine.pyindex cb2adf2ae,000000000..d3cce60f1mode 100644,000000..100644--- a/tests/runtime/test_ts_engine.py+++ b/tests/runtime/test_ts_engine.py@@@ -1,140 -1,0 +1,168 @@@+from __future__ import annotations++import asyncio+from contextvars import ContextVar+from pathlib import Path+import shutil++import pytest+import pytest_asyncio++from deeptutor.runtime.ts_engine.client import EngineClient, EngineUnavailableError++pytestmark = pytest.mark.skipif(+ shutil.which("node") is None+ or not (+ Path(__file__).parents[2] / "packages/chat-engine/dist/src/transport/stdio.js"+ ).is_file(),+ reason="Build the experimental TypeScript engine first",+)++CONFIG = {"explorationBudget": 3, "settlementBudget": 3, "emptyRecoveryBudget": 2}+SCOPE = ContextVar("test_engine_scope", default="missing")+++class Host:+ def __init__(self, *, gate=None, failure=None):+ self.seen = []+ self.gate = gate+ self.failure = failure+ self.entered = asyncio.Event()++ async def invoke(self, operation, args, state):+ self.seen.append((operation, SCOPE.get()))+ if operation == "call_round":+ self.entered.set()+ if self.gate is not None:+ await self.gate.wait()+ if self.failure is not None:+ raise self.failure+ return dict(+ hasTools=False, hasText=True, truncated=False, reasoningBudgetExhausted=False+ )+ if operation == "check_finish":+ return dict(redirect=False, override=False)+ return None+++@pytest_asyncio.fixture+async def client():+ client = EngineClient()+ yield client+ await client.close()+++async def test_shared_worker_preserves_each_turn_context(client):+ async def run(scope):+ token = SCOPE.set(scope)+ try:+ host = Host()+ state = await client.run(host, CONFIG)+ assert state["rounds"] == 1+ assert host.seen == [(op, scope) for op in ["call_round", "check_finish", "finish"]]+ finally:+ SCOPE.reset(token)++ await asyncio.gather(*(run(f"owner-{i}/workspace-{i}") for i in range(12)))+ assert client._runs == {}+++async def test_cancel_one_turn_does_not_cancel_or_replay_its_peer(client):+ host = Host(gate=asyncio.Event())+ waiting = asyncio.create_task(client.run(host, CONFIG))+ await host.entered.wait()+ waiting.cancel()+ with pytest.raises(asyncio.CancelledError):+ await waiting+ survivor = Host()+ assert (await client.run(survivor, CONFIG))["rounds"] == 1+ assert [op for op, _ in host.seen] == ["call_round"]+ assert client._runs == {}+++async def test_typed_host_failure_is_preserved_across_bridge(client):+ error = ValueError("typed original exception")+ with pytest.raises(ValueError) as raised:+ await client.run(Host(failure=error), CONFIG)+ assert raised.value is error+++async def test_worker_failure_does_not_repeat_completed_side_effects(client):+ gate = asyncio.Event()+ host = Host(gate=gate)+ running = asyncio.create_task(client.run(host, CONFIG))+ await host.entered.wait()+ assert client._process is not None+ client._process.kill()+ await client._process.wait()+ with pytest.raises(EngineUnavailableError):+ await asyncio.wait_for(running, timeout=1)+ assert [op for op, _ in host.seen] == ["call_round"]+ # A new turn may create a fresh worker; the failed turn is not retried.+ assert (await client.run(Host(), CONFIG))["rounds"] == 1+++async def test_close_terminates_child_and_fails_pending_turn(client):+ await client._ensure_started()+ process = client._process+ await client.close()+ assert process is not None and process.returncode is not None+++async def test_idle_worker_releases_memory_and_a_new_turn_restarts_it(client, monkeypatch):+ monkeypatch.setattr("deeptutor.runtime.ts_engine.client._IDLE_WORKER_SECONDS", 0.01)+ await client.run(Host(), CONFIG)+ first = client._process+ await asyncio.sleep(0.1)+ assert first is not None and first.returncode is not None+ await client.run(Host(), CONFIG)+ assert client._process is not None and client._process.pid != first.pid+++async def test_idle_cleanup_never_interrupts_a_waiting_peer(client, monkeypatch):+ monkeypatch.setattr("deeptutor.runtime.ts_engine.client._IDLE_WORKER_SECONDS", 0.01)+ gate = asyncio.Event()+ host = Host(gate=gate)+ waiting = asyncio.create_task(client.run(host, CONFIG))+ await host.entered.wait()+ process = client._process+ await client.run(Host(), CONFIG)+ await asyncio.sleep(0.03)+ assert process is not None and process.returncode is None+ gate.set()+ assert (await waiting)["rounds"] == 1++++++async def test_mid_turn_prerequisite_failure_never_salvages_across_bridge(client):++ from deeptutor.core.capability_protocol import CapabilityPrerequisiteError++++ error = CapabilityPrerequisiteError("source unavailable")++ operations = []++++ class PrerequisiteHost:++ async def invoke(self, operation, args, state):++ operations.append(operation)++ if operation == "call_round":++ if state["rounds"]:++ raise error++ return dict(++ hasTools=True, hasText=False, truncated=False, reasoningBudgetExhausted=False++ )++ if operation == "dispatch_tools":++ return {"pause": False}++ if operation == "after_tools":++ return {"override": False, "terminate": False}++ raise AssertionError(f"Unexpected operation: {operation}")++++ with pytest.raises(CapabilityPrerequisiteError) as raised:++ await client.run(PrerequisiteHost(), CONFIG)++ assert raised.value is error++ assert operations == ["call_round", "dispatch_tools", "after_tools", "call_round"]diff --cc web/contracts/generated/api.tsindex 9ac4c030f,379d0d7e5..9754feb09--- a/web/contracts/generated/api.ts+++ b/web/contracts/generated/api.ts@@@ -7903,26 -7644,26 +7903,46 @@@ export interface pathsreadonly patch?: never;readonly trace?: never;};+ readonly "/api/sessions/{session_id}/threads": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /**+ * List Session Threads+ * @description Little Tutor threads opened from this conversation, newest first.+ */+ readonly get: operations["list_session_threads_api_sessions__session_id__threads_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };+ readonly "/api/sessions/capabilities": {+ readonly parameters: {+ readonly query?: never;+ readonly header?: never;+ readonly path?: never;+ readonly cookie?: never;+ };+ /**+ * Session Store Capabilities+ * @description Expose operations the configured store can perform atomically.+ */+ readonly get: operations["session_store_capabilities_api_sessions_capabilities_get"];+ readonly put?: never;+ readonly post?: never;+ readonly delete?: never;+ readonly options?: never;+ readonly head?: never;+ readonly patch?: never;+ readonly trace?: never;+ };readonly "/api/sessions/recycle-bin": {readonly parameters: {readonly query?: never;@@@ -36360,41 -34878,39 +36440,74 @@@ export interface operations};};};+ readonly list_session_threads_api_sessions__session_id__threads_get: {+ 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?: never;+ 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 session_store_capabilities_api_sessions_capabilities_get: {+ readonly parameters: {+ readonly query?: never;+ readonly header?: {+ readonly Authorization?: string | null;+ };+ readonly path?: never;+ readonly cookie?: {+ readonly dt_token?: string | null;+ };+ };+ readonly requestBody?: never;+ readonly responses: {+ /** @description Successful Response */+ readonly 200: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["SessionStoreCapabilities"];+ };+ };+ /** @description Validation Error */+ readonly 422: {+ headers: {+ readonly [name: string]: unknown;+ };+ content: {+ readonly "application/json": components["schemas"]["HTTPValidationError"];+ };+ };+ };+ };readonly list_recycle_bin_api_sessions_recycle_bin_get: {readonly parameters: {readonly query?: {diff --cc web/features/chat/ChatStateAdapter.tsxindex 13d4edaf7,44d56c09f..a0a68a979--- a/web/features/chat/ChatStateAdapter.tsx+++ b/web/features/chat/ChatStateAdapter.tsx@@@ -724,35 -657,8 +741,36 @@@ function isSameTurnEvent(a: StreamEventreturn Boolean(aTurn && bTurn && aTurn === bTurn);}+/**+ * Whether ``event`` is already in ``events``. A turn's events arrive in seq+ * order, so the latest one of the same turn usually settles it at once; only+ * a replay of something older needs the full look. Scanning every event for+ * every new one made a long turn quadratic.+ */+function hasTurnEvent(events: StreamEvent[], event: StreamEvent): boolean {+ const seq = Number(event.seq || 0);+ const turn = event.turn_id || "";+ if (seq <= 0 || !turn) return false;+ for (let index = events.length - 1; index >= 0; index -= 1) {+ const other = events[index];+ const otherSeq = Number(other.seq || 0);+ if ((other.turn_id || "") !== turn || otherSeq <= 0) continue;+ if (otherSeq < seq) return false;+ break;+ }+ return events.some((other) => isSameTurnEvent(other, event));+}+function reducer(state: ProviderState, action: Action): ProviderState {+ const next = reduce(state, action);+ // Opening a conversation from history is how most of them enter memory.+ return action.type === "LOAD_SESSION" && next !== state+ ? { ...next, sessions: trimSessions(next.sessions, next.selectedKey) }+ : next;+}++function reduce(state: ProviderState, action: Action): ProviderState {+ if (action.type === "RESET_ACCOUNT") return initialState;switch (action.type) {case "SET_TOOLS":return updateSelectedSession(state, (session) => ({@@@ -1200,11 -1135,8 +1259,12 @@@messages: settled,isStreaming: false,currentStage: "",+ // What the ended turn never read waits for the next one.+ queuedMessages: (ending?.queuedMessages ?? []).map((queued) =>+ queued.offeredTo ? { ...queued, offeredTo: null } : queued,+ ),status: action.status ?? "completed",+ submissionBaseStatus: action.status ?? "completed",activeTurnId:action.status === "running" || pendingAskUser? action.turnId ||@@@ -2988,12 -2951,7 +3114,12 @@@ export function ChatStateAdapterProvideconst effectiveTimedMediaId = replaySnapshot?.timedMediaId;const effectiveWatchingTurnFields = replaySnapshot?.watchingTurnFields ??(effectiveTimedMediaId ? { timed_media_id: effectiveTimedMediaId } : {});+ // The bubble names who it was handed to, as the stored snapshot will.+ const snapshotConfig =+ session.answerBy && effectiveConfig?.answer_by === undefined+ ? { ...(effectiveConfig ?? {}), answer_by: session.answerBy }+ : effectiveConfig;- const requestSnapshot: MessageRequestSnapshot = replaySnapshot ?? {+ const requestSnapshot: MessageRequestSnapshot = replaySnapshot ? { ...replaySnapshot } : {resourceSelection: {skills:[...effectiveResources.skills],mcp:[...effectiveResources.mcp]},content,capability: effectiveCapability,@@@ -3105,10 -3067,13 +3235,12 @@@parentMessageId: localParentId,failedSubmissionId: submissionId,});- }- dispatch({ type: "STREAM_START", key, startedAt: Date.now() / 1000 });+ }+ dispatch({ type: "STREAM_START", key, startedAt: Date.now() / 1000 });+ };+ if (!replacesSubmissionId) showSubmission();const {_persist_user_message: legacyPersistUserMessage,- _course_id: _legacyCourseId,followup_question_context: followupQuestionContext,selection_tutor_context: selectionTutorContext,subagent_consult_budget: subagentConsultBudget,diff --cc web/features/chat/messages/ChatMessageList.tsxindex 13784006d,6e3ef7f1f..0e38314c8--- a/web/features/chat/messages/ChatMessageList.tsx+++ b/web/features/chat/messages/ChatMessageList.tsx@@@ -96,7 -94,10 +97,6 @@@ import { SetupCredentialCard } from "@/import { extractSetupCredential } from "@/lib/setup-signals";import { PartnerDraftCard } from "@/components/chat/home/PartnerDraftCard";import { extractPartnerDraft } from "@/lib/partner-draft";- import { MasteryHandoffCards } from "@/components/chat/home/MasteryHandoffCard";-import {- extractCourseHandoffs,- stripLeakedHandoffJson,-} from "@/lib/course-handoff";import { extractMasteryHandoffs } from "@/lib/mastery-handoff";import ContextReferenceTree, {type ContextTreeItem,@@@ -125,6 -123,21 +125,17 @@@ const MathAnimatorViewer = dynamic() => import("@/components/math-animator/MathAnimatorViewer"),{ ssr: false },);+ const MasteryQuestionCard = dynamic(+ () => import("@/components/chat/home/MasteryQuestionCard"), { ssr: false },+ );+ const MasterySourcePresentation = dynamic(+ () => import("@/components/chat/home/MasterySourcePresentation").then(module => module.MasterySourcePresentation),+ { ssr: false },+ );-const CourseHandoffCards = dynamic(- () => import("@/components/chat/home/CourseHandoffCard").then(module => module.CourseHandoffCards),- { ssr: false },-);+ const MasteryHandoffCards = dynamic(+ () => import("@/components/chat/home/MasteryHandoffCard").then(module => module.MasteryHandoffCards),+ { ssr: false },+ );const QuizViewer = dynamic(() => import("@/components/quiz/QuizViewer"), {ssr: false,});@@@ -1214,7 -1222,10 +1237,7 @@@ export const AssistantMessage = memo(fureplacing it, and applies to every branch. */}{setupCredential ? <SetupCredentialCard data={setupCredential} /> : null}{partnerDraft ? <PartnerDraftCard data={partnerDraft} /> : null}- <MasteryHandoffCards handoffs={masteryHandoffs} />- {/* Course Study's hand-offs sit last: they are what to do *after* reading- the answer, so they belong below it rather than competing with it. */}- {courseHandoffs.length > 0 && <CourseHandoffCards handoffs={courseHandoffs} />}+ {masteryHandoffs.length > 0 && <MasteryHandoffCards handoffs={masteryHandoffs} />}</>);});diff --cc web/lib/auth.tsindex 8eb738a16,1e1b83761..17304f82e--- a/web/lib/auth.ts+++ b/web/lib/auth.ts@@@ -1,5 -1,6 +1,7 @@@+import { invalidateClientCache } from "./client-cache";+ import { browserStorage } from "@/shared/storage";import { apiFetch, apiUrl, setRuntimeAuthEnabled } from "@/lib/api";+ import { updateRecoveryPrincipal } from "@/lib/recovery-principal";// Auth state is resolved at runtime from the backend (`/api/auth/status`),// not from a build-time/env constant: the browser bundle never sees@@@ -39,9 -43,28 +44,29 @@@ let cachedAuthStatus: { value: AuthStatnull;export function invalidateAuthStatusCache(): void {+ invalidateClientCache("navigation:");+ authGeneration += 1;authStatusRequest = null;cachedAuthStatus = null;+ updateRecoveryPrincipal(null);+ }++ function broadcastAuthBoundary(): void {+ // Notify other tabs to re-check the server, never convey/trust a principal+ // through shared browser storage. No private recovery records are deleted.+ if (typeof window === "undefined") return;+ try { browserStorage.writeRaw("local", AUTH_BOUNDARY_KEY, `${Date.now()}:${Math.random()}`); }+ catch { /* Storage may be unavailable; this tab still fails closed. */ }+ }++ function listenForAuthBoundary(): void {+ if (boundaryListenerInstalled || typeof window === "undefined") return;+ boundaryListenerInstalled = true;+ window.addEventListener("storage", (event) => {+ if (event.key !== AUTH_BOUNDARY_KEY) return;+ invalidateAuthStatusCache();+ void fetchAuthStatus();+ });}/**diff --cc web/lib/relative-time.tsindex 0cb28543b,84026aba4..18bf50575--- a/web/lib/relative-time.ts+++ b/web/lib/relative-time.ts@@@ -29,10 -30,11 +31,10 @@@ export function getDayGroupKey(timestamdate.getFullYear(),date.getMonth(),date.getDate(),- ).getTime();+ );const diffDays = Math.floor((startOfToday - startOfItemDay) / 86400000);if (diffDays <= 0) return "today";- if (diffDays === 1) return "yesterday";- if (diffDays < 7) return "last_7_days";+ if (diffDays < 7) return "this_week";return "earlier";}