Session Tool
Relevant source files
The following files were used as context for generating this wiki page:
- src/infrahub_mcp/tools/session.py
- specs/archive/20260604-141223-session-branch-recovery/plan.md
- specs/archive/20260604-141223-session-branch-recovery/tasks.md
- specs/archive/20260421-144953-production-ready-mcp-server/spec.md
- specs/archive/20260421-144953-production-ready-mcp-server/tasks.md
- dev/knowledge/architecture.md
The Session Tool provides mechanisms for AI agents and operators to interact with and manage the state of an active Infrahub MCP session. It primarily focuses on reporting session metadata, such as the active branch, and managing the lifecycle of session-scoped branches. By isolating infrastructure changes to specific branches, the tool ensures that production data on the default branch remains protected during agent interactions.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:68-71, specs/archive/20260604-141223-session-branch-recovery/plan.md:10-14
Architecture and Session Scoping
The session system uses a WeakKeyDictionary to store session-specific state, such as active branches and locks. This ensures that state is isolated per MCP session (ctx.session_id) rather than being shared across the entire server process. This isolation prevents a branch reset or recovery in one session from disturbing unrelated sessions.
Session State Storage
The server maintains state within the AppContext using the following structures:
_session_branches: AWeakKeyDictionarymapping session objects to branch names._session_locks: AWeakKeyDictionarymapping session objects toasyncio.Lockinstances for serialized access._session_locks_guard: A global lock used to safely manage the creation of per-session locks.
Sources: specs/archive/20260604-141223-session-branch-recovery/plan.md:36-39, specs/archive/20260604-141223-session-branch-recovery/tasks.md:41-44
Session Lifecycle Flow
The following diagram illustrates how the system manages session-scoped branch access and locking.
The diagram shows the sequence of lock acquisition and branch verification performed for every session-aware operation.
Sources: specs/archive/20260604-141223-session-branch-recovery/plan.md:120-135, specs/archive/20260604-141223-session-branch-recovery/tasks.md:46-50
Key Tools and Functions
get_session_info
The get_session_info tool allows users and agents to query the current state of the MCP session. It provides transparency into which branch is currently active and whether a session-specific branch has been provisioned.
Response Fields:
| Field | Type | Description |
|---|---|---|
session_id | str | The unique identifier for the current MCP session. |
session_branch | str | None | The name of the active session branch, or null if none is active. |
is_writable | bool | Indicates if the session is currently capable of performing write operations. |
Sources: src/infrahub_mcp/tools/session.py:1-20, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:139-140
reset_session_branch
The reset_session_branch tool (tagged with "write") allows for manual intervention in the session branch lifecycle. It can be used to clear the current branch cache or switch the session to an explicitly named branch.
- Reset: Calling the tool without arguments clears the cached branch entry for the session.
- Switch/Create: If a branch name is provided, the tool verifies if the name conforms to the configured
branch_pattern. If it conforms but does not exist, the tool creates it. If it exists and is writable, the session switches to it.
Sources: specs/archive/20260604-141223-session-branch-recovery/plan.md:10-14, specs/archive/20260604-141223-session-branch-recovery/tasks.md:112-120
Branch Management and Recovery
The Session Tool implements proactive and reactive recovery to handle cases where a session branch becomes unwritable (e.g., it was merged or is being deleted).
Branch Status Detection
The system monitors BranchData.status. Branches in the following states are considered unwritable:
MERGEDDELETING
If a tool attempt uses a cached branch in one of these states, the system automatically clears the cache, provisions a new branch according to the branch_pattern, and issues a warning to the user.
Sources: specs/archive/20260604-141223-session-branch-recovery/plan.md:30-34, specs/archive/20260604-141223-session-branch-recovery/tasks.md:86-90
Recovery Sequence
The following sequence diagram describes the auto-recovery process when an agent attempts a write on a merged branch.
The diagram represents the logic where the system detects an unwritable status and transparently recovers the session state.
Sources: specs/archive/20260604-141223-session-branch-recovery/plan.md:120-135, specs/archive/20260604-141223-session-branch-recovery/tasks.md:92-98
Configuration and Validation
Branch names must conform to specific patterns and character sets to ensure compatibility with Infrahub and git-ref standards.
- Branch Pattern: Configurable via
branch_pattern, supporting placeholders like{date},{hex}, and{user}. - Conformance: The system uses regex derived from the pattern to validate manual branch switches.
- Allowed Charset: Alphanumeric characters, hyphens, underscores, dots, and slashes.
Sources: specs/archive/20260604-141223-session-branch-recovery/plan.md:36-39, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:72-75
Summary
The Session Tool is a critical component for maintaining safe, isolated, and recoverable infrastructure interactions within Infrahub MCP. By utilizing session-scoped state and proactive branch status monitoring, the tool prevents agent operations from stalling due to branch lifecycle events like merges. It provides both automated recovery for seamless agent operation and manual controls for operators to reset or switch session contexts as needed.