fix: restore mastery updates, persist graph_update_json, wire usage limits

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.

backend/agents/chat_tutor.py

@@ -32,7 +32,7 @@
  read_user_progress_tool,
  search_course_materials_tool,
 )
-from agents.tools.graph import apply_graph_update_tool
+from agents.tools.graph import apply_graph_update_tool, update_mastery_tool
 
 
 TutorMode = Literal["socratic", "expository", "teachback"]
@@ -50,6 +50,12 @@
  "fabricate context.\n\n"
  "Tone: warm, concise, no filler. Use math/code blocks where helpful "
  "(LaTeX `$x^2$`, ```mermaid```, ```plot```). Don't over-explain.\n\n"
+ "Knowledge graph tools:\n"
+ "- apply_graph_update_tool: register NEW concepts the student hasn't seen before.\n"
+ "- update_mastery_tool: adjust mastery on EXISTING concepts this turn. "
+ "Use +0.1 to +0.3 when they answer correctly; −0.05 to −0.1 for gaps. "
+ "Call this at the END of every turn where the student demonstrated "
+ "understanding or revealed a misconception.\n\n"
 )
 
 _SOCRATIC_PROMPT = _SHARED_PREAMBLE + (
@@ -104,6 +110,7 @@
  read_session_history_tool,
  read_user_progress_tool,
  apply_graph_update_tool,
+ update_mastery_tool,
 ]
 
 

backend/agents/deps.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 
@@ -27,10 +27,18 @@ class SaplingDeps:
  that need to scope reads to *this* conversation (e.g.
  read_session_history_tool). Optional — agent runs that don't
  happen inside a session (eval mode, batch tasks) leave it None.
+ graph_updates: Accumulates graph update payloads emitted by tools
+ during a run so the route can persist them in graph_update_json
+ for concepts_covered derivation in end_session.
+ mastery_changes: Accumulates the real before/after mastery deltas
+ returned by apply_graph_update so the route can surface them in
+ the chat response for parity with the legacy path.
  """
 
  user_id: str
  course_id: str | None
  supabase: Any
  request_id: str
  session_id: str | None = None
+ graph_updates: list = field(default_factory=list)
+ mastery_changes: list = field(default_factory=list)

backend/agents/tools/graph.py

@@ -1,21 +1,24 @@
-"""Graph-update helpers and a Pydantic AI tool wrapper.
+"""Graph-update helpers and Pydantic AI tool wrappers.
 
-The core merge logic lives in `apply_concepts_to_graph` — a plain async
-function callable from routes directly. `apply_graph_update_tool` is a
-thin Pydantic AI wrapper around it for future agents that need a tool
-to register on an `Agent`. Neither contains LLM-specific logic; that
-stays in `services.graph_service`.
+Two tools are exposed:
+- apply_graph_update_tool — registers new concepts (new_nodes, initial_mastery 0.0)
+- update_mastery_tool — adjusts mastery on existing concepts (updated_nodes + delta)
+
+Both append their payload to ctx.deps.graph_updates so the route can
+persist graph_update_json on the assistant message, enabling end_session
+to derive concepts_covered correctly for agent-path chats.
 """
 
 from __future__ import annotations
 
 import asyncio
+from typing import Literal
 
 from pydantic import BaseModel, Field
 from pydantic_ai import RunContext
 
 from agents.deps import SaplingDeps
-from services.graph_service import apply_graph_update
+from services.graph_service import _normalize_concept, apply_graph_update
 
 
 class GraphUpdateInput(BaseModel):
@@ -27,6 +30,41 @@ class GraphUpdateInput(BaseModel):
  )
 
 
+class ConceptMasteryUpdate(BaseModel):
+ concept_name: str = Field(
+ description="Exact name of the concept whose mastery score to change."
+ )
+ mastery_delta: float = Field(
+ ge=-1.0,
+ le=1.0,
+ description=(
+ "Fractional mastery change, −1.0 to +1.0. "
+ "Use +0.1 to +0.3 when the student answers correctly; "
+ "−0.05 to −0.1 when they reveal a gap or misconception."
+ ),
+ )
+ reason: str = Field(
+ default="",
+ description="Short phrase shown in the mastery-event log (e.g. 'answered correctly').",
+ )
+ event_type: Literal["interaction", "correction", "quiz"] = Field(
+ default="interaction",
+ description="Event category for the mastery-event log.",
+ )
+
+
+class MasteryUpdateInput(BaseModel):
+ """Typed input for the update_mastery tool."""
+
+ updates: list[ConceptMasteryUpdate] = Field(
+ description=(
+ "One entry per concept whose mastery changed this turn. "
+ "Only include concepts that already exist in the graph "
+ "(or were just added via apply_graph_update_tool)."
+ )
+ )
+
+
 async def apply_concepts_to_graph(
  user_id: str,
  course_id: str | None,
@@ -58,13 +96,82 @@ async def apply_graph_update_tool(
  ctx: RunContext[SaplingDeps],
  update: GraphUpdateInput,
 ) -> str:
- """Pydantic AI tool wrapper around apply_concepts_to_graph.
+ """Register new concepts in the student's knowledge graph.
 
- Returns a short summary string for the agent to confirm the operation.
+ Call this when a new topic comes up that isn't already tracked.
+ To raise or lower mastery on an existing concept, call update_mastery_tool.
  """
- count = await apply_concepts_to_graph(
- ctx.deps.user_id, ctx.deps.course_id, update.concepts,
- )
- if count == 0:
+ new_nodes = [
+ {"concept_name": name.strip(), "initial_mastery": 0.0}
+ for name in update.concepts
+ if name and name.strip()
+ ]
+ if not new_nodes:
  return "Graph update skipped: no concepts to add."
- return f"Graph updated: {count} concept(s) merged."
+ await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"new_nodes": new_nodes},
+ ctx.deps.course_id,
+ )
+ ctx.deps.graph_updates.append({"new_nodes": new_nodes})
+ return f"Graph updated: {len(new_nodes)} concept(s) merged."
+
+
+async def update_mastery_tool(
+ ctx: RunContext[SaplingDeps],
+ update: MasteryUpdateInput,
+) -> str:
+ """Adjust mastery scores for concepts the student engaged with this turn.
+
+ Positive delta (e.g. +0.15) when they demonstrate understanding;
+ negative (e.g. −0.08) when they reveal a gap. Concepts must already
+ exist in the graph — call apply_graph_update_tool first if needed.
+ """
+ updated_nodes = [
+ {
+ "concept_name": u.concept_name.strip(),
+ "mastery_delta": u.mastery_delta,
+ "reason": u.reason,
+ "event_type": u.event_type,
+ }
+ for u in update.updates
+ if u.concept_name and u.concept_name.strip()
+ ]
+ if not updated_nodes:
+ return "Mastery update skipped: no concepts provided."
+
+ changes = await asyncio.to_thread(
+ apply_graph_update,
+ ctx.deps.user_id,
+ {"updated_nodes": updated_nodes},
+ ctx.deps.course_id,
+ )
+
+ # Only persist concepts that actually produced a change. A concept the
+ # model named but that doesn't exist in the graph yields no `changes`
+ # and is never written, so it must not leak into graph_update_json (it
+ # would over-report concepts_covered in end_session). Rebuild the
+ # appended updated_nodes from the concepts that genuinely changed.
+ #
+ # `changes` carries the *stored* concept_name while `updated_nodes` holds
+ # the *model-provided* spelling; match on the normalized form (the same
+ # case/whitespace-insensitive key apply_graph_update dedups on) so a
+ # casing/spacing drift doesn't drop a genuinely-changed concept.
+ if changes:
+ changed_names = {_normalize_concept(c["concept"]) for c in changes}
+ persisted_nodes = [
+ n
+ for n in updated_nodes
+ if _normalize_concept(n["concept_name"]) in changed_names
+ ]
+ if persisted_nodes:
+ ctx.deps.graph_updates.append({"updated_nodes": persisted_nodes})
+ # Surface the real before/after deltas for parity with the legacy path.
+ ctx.deps.mastery_changes.extend(changes)
+ parts = [f"{c['concept']} {c['before']:.2f}→{c['after']:.2f}" for c in changes]
+ return f"Mastery updated: {', '.join(parts)}."
+ return (
+ f"Mastery update processed ({len(updated_nodes)} concept(s)); "
+ "no score change — concept may not exist yet. Call apply_graph_update_tool first."
+ )

backend/routes/learn.py

@@ -11,6 +11,7 @@
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.chat_tutor import agent_for_mode
 from agents.deps import SaplingDeps
 from db.connection import table
@@ -512,10 +513,12 @@ async def _chat_via_agent(
  """Run chat_tutor_agent and return the legacy response shape.
 
  Returns ``{"reply": str, "graph_update": dict, "mastery_changes": list}``.
- `graph_update` and `mastery_changes` come back empty here because
- `apply_graph_update_tool` (registered on chat_tutor) already
- persisted any graph changes during the agent run. The frontend's
- Learn-page reducer accepts empty values gracefully.
+ Graph changes are persisted in-band during the agent run by
+ `apply_graph_update_tool` / `update_mastery_tool` (registered on
+ chat_tutor); the tools also accumulate their payloads on `deps` so the
+ route can echo `graph_update` (for graph_update_json / concepts_covered)
+ and the real `mastery_changes` deltas back to the client, matching the
+ legacy path. Both are empty when nothing changed this turn.
 
  `use_shared_context=False` flips the model into "no class-aggregate"
  mode by appending a constraint instruction to the user message —
@@ -563,7 +566,11 @@ async def _chat_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps, "message_history": message_history}
+ run_kwargs: dict = {
+ "deps": deps,
+ "message_history": message_history,
+ "usage_limits": ORCHESTRATOR_LIMITS,
+ }
  if model_override is not None:
  run_kwargs["model"] = model_override
 
@@ -576,10 +583,21 @@ async def _chat_via_agent(
  result = await agent.run(user_message, **run_kwargs)
  reply = result.output # str — chat_tutor agents return plain Markdown.
 
+ # Merge all graph update payloads accumulated by tools during this run
+ # into a single dict so the route can persist graph_update_json and
+ # end_session can derive concepts_covered correctly.
+ merged_graph_update: dict = {}
+ for gu in deps.graph_updates:
+ for key, items in gu.items():
+ merged_graph_update.setdefault(key, []).extend(items)
+
  return {
  "reply": reply,
- "graph_update": {},
- "mastery_changes": [],
+ "graph_update": merged_graph_update,
+ # Real before/after deltas accumulated by update_mastery_tool, for
+ # parity with the legacy path (which returns apply_graph_update's
+ # changes directly). Empty when no mastery moved this turn.
+ "mastery_changes": deps.mastery_changes,
  }
 
 
@@ -690,7 +708,8 @@ async def chat(body: ChatBody, request: Request):
  # own writes so a fallback doesn't double-insert. Encryption happens
  # inside save_message (`encrypt_if_present`).
  save_message(body.session_id, "user", body.message)
- save_message(body.session_id, "assistant", response["reply"])
+ graph_update = response.get("graph_update") or None
+ save_message(body.session_id, "assistant", response["reply"], graph_update)
 
  return response
 

backend/routes/quiz.py

@@ -8,6 +8,7 @@
 
 from pydantic_ai.exceptions import UsageLimitExceeded, UnexpectedModelBehavior
 
+from agents import ORCHESTRATOR_LIMITS
 from agents.quiz import quiz_agent, Quiz, QuizQuestion
 from agents.deps import SaplingDeps
 from agents._run import run_agent_sync
@@ -186,7 +187,7 @@ async def _quiz_via_agent(
  )
 
  model_override = _resolve_model_pref(model_pref)
- run_kwargs: dict = {"deps": deps}
+ run_kwargs: dict = {"deps": deps, "usage_limits": ORCHESTRATOR_LIMITS}
  if model_override is not None:
  run_kwargs["model"] = model_override
  result = await quiz_agent.run(user_message, **run_kwargs)

backend/tests/test_chat_tutor_imports.py

@@ -34,13 +34,14 @@ def test_unknown_mode_falls_back_to_socratic():
  assert agent_for_mode(None) is socratic_agent
 
 
-def test_all_four_tools_registered():
- """Chat tutor needs three context tools + the graph-update tool."""
+def test_all_tools_registered():
+ """Chat tutor needs three context tools + two graph tools (add and update mastery)."""
  expected = {
  "search_course_materials_tool",
  "read_session_history_tool",
  "read_user_progress_tool",
  "apply_graph_update_tool",
+ "update_mastery_tool",
  }
  # Pydantic AI 1.89's tool registry is at agent._function_toolset.tools
  # (dict keyed by tool name) — see commit a850d31 for the gotcha.