DM20 Protocol

Instructions

Implementation Reference

• src/dm20_protocol/claudmaster/tools/session_tools.py:1202-1337 (handler)

  Implementation of the 'get_session_state' tool. Note: In the code, the function name is 'get_session_state', but it corresponds to the 'get_sessions' entry in the permissions registry.

  async def get_session_state(
      session_id: str,
      detail_level: str = "standard",
      include_history: bool = True,
      history_limit: int = 10,
  ) -> dict:
      """
      Get the current state of a Claudmaster session.
  
      This MCP tool queries the state of an active session, returning
      information about the game state, party, recent history, and
      session metadata. Supports multiple detail levels.
  
      Args:
          session_id: The session ID to query
          detail_level: How much detail to include:
              - "minimal": Basic session info and status only
              - "standard": Session info, game state, party status, recent history
              - "full": Everything including complete context budget analysis
          include_history: Whether to include action history in the response
          history_limit: Maximum number of history entries to return (default: 10)
  
      Returns:
          Dictionary with the following keys:
              - session_info: Basic session metadata (id, status, campaign, duration)
              - game_state: Current game state (location, combat, turn count)
              - party_status: List of character summaries with status
              - recent_history: Last N actions (if include_history=True)
              - active_quests: Current quest status (placeholder)
              - context_usage: Context window utilization info
              - error_message: Error description if session not found
  
      Examples:
          Get standard session state:
          >>> result = await get_session_state(session_id="abc123")
  
          Get minimal info (fast):
          >>> result = await get_session_state(
          ...     session_id="abc123",
          ...     detail_level="minimal"
          ... )
  
          Get full state with extended history:
          >>> result = await get_session_state(
          ...     session_id="abc123",
          ...     detail_level="full",
          ...     history_limit=50
          ... )
      """
      try:
          # Validate detail level
          valid_levels = ("minimal", "standard", "full")
          if detail_level not in valid_levels:
              return {
                  "error_message": (
                      f"*The DM adjusts their spectacles*\n\n"
                      f"I don't recognize the '{detail_level}' level of detail. "
                      f"Please choose from: {', '.join(valid_levels)}."
                  )
              }
  
          # Get session state from manager
          state = _session_manager.get_session_state(session_id)
  
          if state is None:
              return {
                  "error_message": _error_formatter.format_session_not_found(session_id)
              }
  
          # Get raw session for additional details
          orchestrator, session = _session_manager._active_sessions[session_id]
  
          # Calculate duration
          duration_minutes = int((datetime.now() - session.started_at).total_seconds() / 60)
  
          # Build session_info (always included)
          session_info = {
              "session_id": state.session_id,
              "status": state.status,
              "campaign_id": state.campaign_info.campaign_id,
              "campaign_name": state.campaign_info.campaign_name,
              "duration_minutes": duration_minutes,
              "turn_count": session.turn_count,
          }
  
          # Minimal level: just session info
          if detail_level == "minimal":
              return {"session_info": session_info}
  
          # Standard and full: add game state and party
          game_state = state.game_state.model_dump()
          party_status = [char.model_dump() for char in state.party_info]
  
          # Build history if requested
          recent_history: list[dict] = []
          if include_history:
              limit = history_limit if detail_level == "standard" else max(history_limit, 50)
              for msg in session.conversation_history[-limit:]:
                  recent_history.append(msg)
  
          # Context usage
          context_usage = {
              "context_budget_remaining": state.context_budget,
              "max_tokens": session.config.max_tokens,
          }
  
          # Full level: add extra detail
          if detail_level == "full":
              context_usage["conversation_length"] = len(session.conversation_history)
              context_usage["active_agents"] = dict(session.active_agents)
  
          # Build active quests from campaign data
          active_quests = []
          if _storage:
              campaign = _storage.get_current_campaign()
              if campaign:
                  active_quests = [
                      {"title": quest.title, "status": quest.status, "giver": quest.giver}
                      for quest in campaign.quests.values()
                      if quest.status == "active"
                  ]
  
          return {
              "session_info": session_info,
              "game_state": game_state,
              "party_status": party_status,
              "recent_history": recent_history,
              "active_quests": active_quests,
              "context_usage": context_usage,
          }
  
      except Exception as e:
          logger.error(f"Error in get_session_state for {session_id}: {e}", exc_info=True)
          return {
              "error_message": _error_formatter.format_error(e)
          }