Skip to content

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

Merge dev into preview, preserving preview features

Bingxi Zhao (Frank)6bbcc00c55a9
diff --cc README.md
index 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.py
index 840db1ac7,000000000..1249d18da
mode 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.outcome
diff --cc deeptutor/agents/loop/python_scheduler.py
index d55955926,000000000..2957d77e6
mode 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 state
diff --cc deeptutor/api/routers/auth.py
index 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.py
index 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 [
row
for 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.py
index 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.py
index d4acaf600,be4d6d610..43ccb248d
--- a/deeptutor/runtime/coordination/memory.py
+++ b/deeptutor/runtime/coordination/memory.py
@@@ -148,8 -97,15 +148,15 @@@ class MemoryCoordinator
async 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.py
index a63982f64,000000000..397e74808
mode 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.py
index 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(c
return "\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.py
index 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, field
import json
import logging
+import os
+ import re
from typing import Any, Awaitable, Callable
from deeptutor.agents.base_agent import BaseAgent
diff --cc deeptutor/services/session/pocketbase_store.py
index 079b77564,c466bf803..0435d24bb
--- a/deeptutor/services/session/pocketbase_store.py
+++ b/deeptutor/services/session/pocketbase_store.py
@@@ -819,11 -835,12 +835,14 @@@ class PocketBaseSessionStore
record = _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 True
diff --cc deeptutor/services/session/protocol.py
index cd0b81d7a,54e1f16ca..658a0f8a3
--- a/deeptutor/services/session/protocol.py
+++ b/deeptutor/services/session/protocol.py
@@@ -247,10 -247,12 +247,12 @@@ class SessionStoreProtocol(SessionRepos
session_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.py
index c13b6a0da,f69e60008..5b4b95338
--- a/deeptutor/services/session/sqlite_store.py
+++ b/deeptutor/services/session/sqlite_store.py
@@@ -3078,11 -3185,11 +3186,11 @@@ class SQLiteSessionStore
conn.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.ts
index da79ad423,000000000..9948d233a
mode 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.ts
index f7ecd4f76,000000000..33564ca76
mode 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.ts
index 38f285d61,000000000..15e631c26
mode 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.ts
index 74c0ee848,000000000..9724374e2
mode 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.ts
index 7a1795483,000000000..75d2b7f49
mode 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.toml
index 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.py
index 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_fol
assert "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.py
index 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_sin
assert 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.py
index cb2adf2ae,000000000..d3cce60f1
mode 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.ts
index 9ac4c030f,379d0d7e5..9754feb09
--- a/web/contracts/generated/api.ts
+++ b/web/contracts/generated/api.ts
@@@ -7903,26 -7644,26 +7903,46 @@@ export interface paths
readonly 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.tsx
index 13d4edaf7,44d56c09f..a0a68a979
--- a/web/features/chat/ChatStateAdapter.tsx
+++ b/web/features/chat/ChatStateAdapter.tsx
@@@ -724,35 -657,8 +741,36 @@@ function isSameTurnEvent(a: StreamEvent
return 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 ChatStateAdapterProvide
const 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.tsx
index 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(fu
replacing 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.ts
index 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: AuthStat
null;
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.ts
index 0cb28543b,84026aba4..18bf50575
--- a/web/lib/relative-time.ts
+++ b/web/lib/relative-time.ts
@@@ -29,10 -30,11 +31,10 @@@ export function getDayGroupKey(timestam
date.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";
}