feat: flexible intake — deferred variables + prepared sessions

Remove blocking intake form modal. Variables are now filled inline during flow execution or pre-filled via prepared sessions. Adds PATCH /sessions/{id}/variables endpoint, POST /sessions/prepare for session pre-staging, inline variable prompts in StepDetail, editable Session Variables panel, and "Prepared for You" dashboard section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-10 01:42:52 -04:00
parent 4727106141
commit 299dff8bfc
22 changed files with 1117 additions and 95 deletions
--- a/backend/app/api/endpoints/sessions.py
+++ b/backend/app/api/endpoints/sessions.py
@@ -21,6 +21,8 @@ from app.schemas.session import (
    SaveAsTreeRequest,
    SaveAsTreeResponse,
    SessionComplete,
+    SessionVariablesUpdate,
+    PrepareSessionRequest,
 )
 from app.api.deps import get_current_active_user
 from app.core.permissions import can_access_tree
@@ -39,6 +41,8 @@ async def list_sessions(
    tree_name: Optional[str] = Query(None, description="Filter by tree name from snapshot"),
    tree_id: Optional[UUID] = Query(None, description="Filter by tree ID"),
    batch_id: Optional[UUID] = Query(None, description="Filter by batch ID (maintenance batch runs)"),
+    assigned_to_id: Optional[UUID] = Query(None, description="Filter by assigned user ID (prepared sessions)"),
+    status: Optional[str] = Query(None, description="Filter by status: prepared, active, completed"),
    started_after: Optional[datetime] = Query(None, description="Filter sessions started after this datetime"),
    started_before: Optional[datetime] = Query(None, description="Filter sessions started before this datetime"),
    completed_after: Optional[datetime] = Query(None, description="Filter sessions completed after this datetime"),
@@ -49,7 +53,11 @@ async def list_sessions(
    limit: int = Query(50, ge=1, le=100)
 ):
    """List user's troubleshooting sessions with comprehensive filtering."""
-    query = select(Session).where(Session.user_id == current_user.id)
+    from sqlalchemy import or_
+    # Show sessions owned by user OR assigned to user (prepared sessions)
+    query = select(Session).where(
+        or_(Session.user_id == current_user.id, Session.assigned_to_id == current_user.id)
+    )

    # Completion status filter
    if completed is not None:
@@ -78,6 +86,18 @@ async def list_sessions(
    if batch_id:
        query = query.where(Session.batch_id == batch_id)

+    # Assigned user filter (for prepared sessions)
+    if assigned_to_id:
+        query = query.where(Session.assigned_to_id == assigned_to_id)
+
+    # Status filter: prepared (started_at IS NULL), active, completed
+    if status == "prepared":
+        query = query.where(Session.started_at.is_(None))
+    elif status == "active":
+        query = query.where(Session.started_at.isnot(None), Session.completed_at.is_(None))
+    elif status == "completed":
+        query = query.where(Session.completed_at.isnot(None))
+
    # Date range filters
    if started_after:
        query = query.where(Session.started_at >= started_after)
@@ -93,7 +113,7 @@ async def list_sessions(
    if page is not None:
        effective_skip = (page - 1) * effective_limit

-    query = query.order_by(Session.started_at.desc())
+    query = query.order_by(Session.started_at.desc().nullslast())
    query = query.offset(effective_skip).limit(effective_limit)

    result = await db.execute(query)
@@ -117,7 +137,7 @@ async def get_session(
            detail="Session not found"
        )

-    if session.user_id != current_user.id:
+    if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="You don't have access to this session"
@@ -155,18 +175,9 @@ async def start_session(
            detail="You don't have access to this tree"
        )

-    # For procedural trees with intake forms, validate required fields
+    # Deferred variables: sessions can start with empty/partial variables
+    # Variables are filled inline during execution via PATCH /sessions/{id}/variables
    session_variables = session_data.session_variables or {}
-    if tree.tree_type == 'procedural' and tree.intake_form:
-        missing_fields = []
-        for field in tree.intake_form:
-            if field.get("required") and not session_variables.get(field["variable_name"]):
-                missing_fields.append(field["label"])
-        if missing_fields:
-            raise HTTPException(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-                detail=f"Missing required intake form fields: {', '.join(missing_fields)}"
-            )

    # Create session with tree snapshot (includes tree metadata for filtering/export)
    tree_snapshot = {
@@ -217,7 +228,7 @@ async def update_session(
            detail="Session not found"
        )

-    if session.user_id != current_user.id:
+    if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="You don't have access to this session"
@@ -229,6 +240,13 @@ async def update_session(
            detail="Cannot update a completed session"
        )

+    # Start a prepared session on first update (set started_at)
+    if session.started_at is None:
+        session.started_at = datetime.now(timezone.utc)
+        # Transfer ownership to the executing user if they're the assignee
+        if session.assigned_to_id == current_user.id and session.user_id != current_user.id:
+            session.user_id = current_user.id
+
    # Use mode='json' to ensure datetime fields are serialized as ISO strings for JSONB storage
    update_data = session_data.model_dump(exclude_unset=True, mode='json')

@@ -257,7 +275,7 @@ async def complete_session(
            detail="Session not found"
        )

-    if session.user_id != current_user.id:
+    if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="You don't have access to this session"
@@ -295,7 +313,7 @@ async def update_scratchpad(
            detail="Session not found"
        )

-    if session.user_id != current_user.id:
+    if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="You don't have access to this session"
@@ -307,6 +325,45 @@ async def update_scratchpad(
    return session


+@router.patch("/{session_id}/variables", response_model=SessionResponse)
+async def update_session_variables(
+    session_id: UUID,
+    data: SessionVariablesUpdate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)]
+):
+    """Update session variables (partial dict merge). Used for deferred variable input."""
+    result = await db.execute(select(Session).where(Session.id == session_id))
+    session = result.scalar_one_or_none()
+
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Session not found"
+        )
+
+    if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this session"
+        )
+
+    if session.completed_at:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Cannot update variables on a completed session"
+        )
+
+    # Merge new variables into existing ones
+    existing = session.session_variables or {}
+    merged = {**existing, **data.variables}
+    session.session_variables = merged
+
+    await db.commit()
+    await db.refresh(session)
+    return session
+
+
@router.post("/{session_id}/export")
 async def export_session(
    session_id: UUID,
@@ -324,7 +381,7 @@ async def export_session(
            detail="Session not found"
        )

-    if session.user_id != current_user.id:
+    if session.user_id != current_user.id and session.assigned_to_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="You don't have access to this session"
@@ -508,6 +565,89 @@ async def save_session_as_tree(
    )


+# ── Prepare Session (Flexible Intake) ─────────────────────────────────────
+
+
+@router.post("/prepare", response_model=SessionResponse, status_code=status.HTTP_201_CREATED)
+async def prepare_session(
+    data: PrepareSessionRequest,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    current_user: Annotated[User, Depends(get_current_active_user)]
+):
+    """Create a prepared session with pre-filled variables and optional assignee.
+
+    Prepared sessions have started_at = NULL. They appear in the assigned
+    engineer's queue and can be started later with variables already filled.
+    """
+    # Get the tree
+    result = await db.execute(select(Tree).where(Tree.id == data.tree_id))
+    tree = result.scalar_one_or_none()
+
+    if not tree:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Tree not found"
+        )
+
+    if not tree.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Cannot prepare session with inactive tree"
+        )
+
+    if not can_access_tree(current_user, tree):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this tree"
+        )
+
+    # Validate assignee exists and is on the same team (if specified)
+    if data.assigned_to_id:
+        assignee_result = await db.execute(select(User).where(User.id == data.assigned_to_id))
+        assignee = assignee_result.scalar_one_or_none()
+        if not assignee:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Assigned user not found"
+            )
+        if current_user.team_id and assignee.team_id != current_user.team_id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Can only assign to users on your team"
+            )
+
+    # Create tree snapshot
+    tree_snapshot = {
+        **tree.tree_structure,
+        "name": tree.name,
+        "description": tree.description,
+        "category": tree.category,
+        "version": tree.version,
+        "tree_type": tree.tree_type,
+    }
+
+    session_variables = data.session_variables or {}
+
+    new_session = Session(
+        tree_id=tree.id,
+        user_id=data.assigned_to_id or current_user.id,
+        tree_snapshot=tree_snapshot,
+        path_taken=[],
+        decisions=[],
+        session_variables=session_variables,
+        ticket_number=data.ticket_number,
+        client_name=data.client_name,
+        started_at=None,  # NULL = prepared state
+        prepared_by_id=current_user.id,
+        assigned_to_id=data.assigned_to_id,
+    )
+
+    db.add(new_session)
+    await db.commit()
+    await db.refresh(new_session)
+    return new_session
+
+
 # ── Batch Launch (Maintenance Flows) ──────────────────────────────────────


--- a/backend/app/models/session.py
+++ b/backend/app/models/session.py
@@ -35,8 +35,9 @@ class Session(Base):
    path_taken: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
    decisions: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, default=list)
    custom_steps: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, default=list)
-    started_at: Mapped[datetime] = mapped_column(
+    started_at: Mapped[Optional[datetime]] = mapped_column(
        DateTime(timezone=True),
+        nullable=True,
        default=lambda: datetime.now(timezone.utc),
        index=True
    )
@@ -60,9 +61,25 @@ class Session(Base):
        Text, nullable=True, server_default=sa.text("''")
    )

+    # Prepared sessions (flexible intake)
+    prepared_by_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id"),
+        nullable=True,
+        index=True
+    )
+    assigned_to_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id"),
+        nullable=True,
+        index=True
+    )
+
    # Relationships
    tree: Mapped["Tree"] = relationship("Tree", back_populates="sessions")
-    user: Mapped["User"] = relationship("User", back_populates="sessions")
+    user: Mapped["User"] = relationship("User", foreign_keys=[user_id], back_populates="sessions")
+    prepared_by: Mapped[Optional["User"]] = relationship("User", foreign_keys=[prepared_by_id])
+    assigned_to: Mapped[Optional["User"]] = relationship("User", foreign_keys=[assigned_to_id])
    attachments: Mapped[list["Attachment"]] = relationship("Attachment", back_populates="session")
    shares: Mapped[list["SessionShare"]] = relationship("SessionShare", back_populates="session", cascade="all, delete-orphan")

--- a/backend/app/models/user.py
+++ b/backend/app/models/user.py
@@ -99,7 +99,7 @@ class User(Base):
    owned_account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys="[Account.owner_id]", back_populates="owner", uselist=False)
    team: Mapped[Optional["Team"]] = relationship("Team", back_populates="users")
    trees: Mapped[list["Tree"]] = relationship("Tree", foreign_keys="[Tree.author_id]", back_populates="author")
-    sessions: Mapped[list["Session"]] = relationship("Session", back_populates="user")
+    sessions: Mapped[list["Session"]] = relationship("Session", foreign_keys="[Session.user_id]", back_populates="user")
    folders: Mapped[list["UserFolder"]] = relationship("UserFolder", back_populates="user")

    @property
--- a/backend/app/schemas/session.py
+++ b/backend/app/schemas/session.py
@@ -55,6 +55,15 @@ class SessionUpdate(BaseModel):
    session_variables: Optional[dict[str, str]] = None


+class PrepareSessionRequest(BaseModel):
+    """Create a prepared session with pre-filled variables and optional assignee."""
+    tree_id: UUID
+    session_variables: Optional[dict[str, str]] = Field(None, description="Pre-filled intake form values")
+    assigned_to_id: Optional[UUID] = Field(None, description="User ID of the engineer to assign this session to")
+    ticket_number: Optional[str] = Field(None, max_length=100)
+    client_name: Optional[str] = Field(None, max_length=255)
+
+
 class SessionResponse(BaseModel):
    id: UUID
    tree_id: UUID
@@ -63,7 +72,7 @@ class SessionResponse(BaseModel):
    path_taken: list[str]
    decisions: list[dict[str, Any]]
    custom_steps: list[dict[str, Any]] = Field(default_factory=list)
-    started_at: datetime
+    started_at: Optional[datetime] = None
    completed_at: Optional[datetime] = None
    outcome: Optional[SessionOutcome] = None
    outcome_notes: Optional[str] = None
@@ -74,6 +83,10 @@ class SessionResponse(BaseModel):
    scratchpad: str = ""
    session_variables: dict[str, str] = Field(default_factory=dict)

+    # Prepared session fields
+    prepared_by_id: Optional[UUID] = None
+    assigned_to_id: Optional[UUID] = None
+
    @validator('scratchpad', 'next_steps', pre=True, always=True)
    def normalize_text_fields(cls, v):
        return v or ""
@@ -106,6 +119,11 @@ class SessionComplete(BaseModel):
    next_steps: Optional[str] = None


+class SessionVariablesUpdate(BaseModel):
+    """Partial update to session variables (dict merge)."""
+    variables: dict[str, str] = Field(..., description="Key-value pairs to merge into session_variables")
+
+
 class ScratchpadUpdate(BaseModel):
    scratchpad: str