feat(l1): advance_ai_build — record answer + generate next node

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend/app/services/l1_session_service.py

@@ -13,6 +13,7 @@ from app.core.audit import log_audit
 from app.models.flow_proposal import FlowProposal
 from app.models.l1_walk_session import L1WalkSession
 from app.models.user import User
+from app.services import ai_tree_builder
 from app.services import internal_ticket_service
 
 
@@ -120,6 +121,60 @@ async def start_ai_build_session(
     return session
 
 
+async def advance_ai_build(
+    db: AsyncSession,
+    *,
+    session_id: UUID,
+    problem_text: str,
+    category: str,
+    node_id: Optional[str] = None,
+    node_text: Optional[str] = None,
+    answer: Optional[str] = None,
+    note: Optional[str] = None,
+) -> dict:
+    """Append the answered/acked node to walked_path, then generate the next node.
+
+    On the first call (node_id is None) nothing is appended — we just generate the
+    first node. Returns the next node dict (caller persists current_node_id).
+    Raises ValueError on missing/inactive/non-ai_build session.
+
+    ``node_text`` is the display text of the node being answered. It is supplied by
+    the caller/endpoint, which holds the served node. Storing it here ensures that
+    later nodes receive full prior-step context via ``ai_tree_builder._build_context``
+    and that captured flywheel trees (``normalize_walked_path``) have meaningful text.
+    """
+    session = await db.get(L1WalkSession, session_id)
+    if not session:
+        raise ValueError(f"L1WalkSession {session_id} not found")
+    if session.session_kind != "ai_build":
+        raise ValueError("advance_ai_build requires an ai_build session")
+    if session.status != "active":
+        raise ValueError(f"Session {session_id} is not active (status={session.status})")
+
+    if node_id is not None:
+        # node_type inferred from the answer: questions are answered yes/no;
+        # instructions are acknowledged (answer is None) per the next-node endpoint contract.
+        # Note: entry uses key "id" (not "node_id" as record_step uses) because
+        # ai_tree_builder.normalize_walked_path reads step.get("id"); the two coexist
+        # safely because they are segregated by session_kind.
+        entry = {
+            "node_type": "question" if answer in ("yes", "no") else "instruction",
+            "id": node_id,
+            "text": node_text or "",
+            "answer": answer,
+            "l1_note": note,
+        }
+        # JSONB requires assigning a new list — in-place mutation isn't tracked
+        session.walked_path = [*session.walked_path, entry]
+
+    next_node = await ai_tree_builder.generate_next_node(
+        problem_text, category, session.walked_path)
+    session.current_node_id = next_node.get("id")
+    session.last_step_at = datetime.now(timezone.utc)
+    await db.flush()
+    return next_node
+
+
 async def record_step(
     db: AsyncSession,
     *,