shotgun-sh 0.2.11.dev2__py3-none-any.whl → 0.2.11.dev3__py3-none-any.whl

shotgun/agents/context_analyzer/analyzer.py

@@ -67,26 +67,13 @@ class ContextAnalyzer:
         for msg in reversed(message_history):
             if isinstance(msg, ModelResponse) and msg.usage:
                 last_input_tokens = msg.usage.input_tokens + msg.usage.cache_read_tokens
-                logger.debug(
-                    f"[ANALYZER] Found last response with usage - "
-                    f"input_tokens={msg.usage.input_tokens}, "
-                    f"cache_read_tokens={msg.usage.cache_read_tokens}, "
-                    f"total={last_input_tokens}"
-                )
                 break
 
         if last_input_tokens == 0:
-            logger.warning(
-                f"[ANALYZER] No usage data found in message history! "
-                f"message_count={len(message_history)}, "
-                f"response_count={sum(1 for m in message_history if isinstance(m, ModelResponse))}"
-            )
-            # Fallback to token estimation
-            logger.info("[ANALYZER] Falling back to token estimation")
+            # Fallback to token estimation (no logging to reduce verbosity)
             last_input_tokens = await estimate_tokens_from_messages(
                 message_history, self.model_config
             )
-            logger.debug(f"[ANALYZER] Estimated tokens: {last_input_tokens}")
 
         # Step 2: Calculate total output tokens (sum across all responses)
         for msg in message_history:
@@ -247,16 +234,7 @@ class ContextAnalyzer:
             # If no content, put all in agent responses
             agent_response_tokens = total_output_tokens
 
-        logger.debug(
-            f"Token allocation complete: user={user_tokens}, agent_responses={agent_response_tokens}, "
-            f"system_prompts={system_prompt_tokens}, system_status={system_status_tokens}, "
-            f"codebase_understanding={codebase_understanding_tokens}, "
-            f"artifact_management={artifact_management_tokens}, web_research={web_research_tokens}, "
-            f"unknown={unknown_tokens}"
-        )
-        logger.debug(
-            f"Input tokens (from last response): {last_input_tokens}, Output tokens (sum): {total_output_tokens}"
-        )
+        # Token allocation complete (no logging to reduce verbosity)
 
         # Create TokenAllocation model
         return TokenAllocation(

shotgun/agents/conversation_manager.py

@@ -1,11 +1,15 @@
 """Manager for handling conversation persistence operations."""
 
+import asyncio
 import json
-import shutil
 from pathlib import Path
 
+import aiofiles
+import aiofiles.os
+
 from shotgun.logging_config import get_logger
 from shotgun.utils import get_shotgun_home
+from shotgun.utils.file_system_utils import async_copy_file
 
 from .conversation_history import ConversationHistory
 
@@ -27,14 +31,14 @@ class ConversationManager:
         else:
             self.conversation_path = conversation_path
 
-    def save(self, conversation: ConversationHistory) -> None:
+    async def save(self, conversation: ConversationHistory) -> None:
         """Save conversation history to file.
 
         Args:
             conversation: ConversationHistory to save
         """
         # Ensure directory exists
-        self.conversation_path.parent.mkdir(parents=True, exist_ok=True)
+        await aiofiles.os.makedirs(self.conversation_path.parent, exist_ok=True)
 
         try:
             # Update timestamp
@@ -44,9 +48,12 @@ class ConversationManager:
 
             # Serialize to JSON using Pydantic's model_dump
             data = conversation.model_dump(mode="json")
+            json_content = json.dumps(data, indent=2, ensure_ascii=False)
 
-            with open(self.conversation_path, "w", encoding="utf-8") as f:
-                json.dump(data, f, indent=2, ensure_ascii=False)
+            async with aiofiles.open(
+                self.conversation_path, "w", encoding="utf-8"
+            ) as f:
+                await f.write(json_content)
 
             logger.debug("Conversation saved to %s", self.conversation_path)
 
@@ -56,19 +63,20 @@ class ConversationManager:
             )
             # Don't raise - we don't want to interrupt the user's session
 
-    def load(self) -> ConversationHistory | None:
+    async def load(self) -> ConversationHistory | None:
         """Load conversation history from file.
 
         Returns:
             ConversationHistory if file exists and is valid, None otherwise
         """
-        if not self.conversation_path.exists():
+        if not await aiofiles.os.path.exists(self.conversation_path):
             logger.debug("No conversation history found at %s", self.conversation_path)
             return None
 
         try:
-            with open(self.conversation_path, encoding="utf-8") as f:
-                data = json.load(f)
+            async with aiofiles.open(self.conversation_path, encoding="utf-8") as f:
+                content = await f.read()
+                data = json.loads(content)
 
             conversation = ConversationHistory.model_validate(data)
             logger.debug(
@@ -89,7 +97,7 @@ class ConversationManager:
             # Create a backup of the corrupted file for debugging
             backup_path = self.conversation_path.with_suffix(".json.backup")
             try:
-                shutil.copy2(self.conversation_path, backup_path)
+                await async_copy_file(self.conversation_path, backup_path)
                 logger.info("Backed up corrupted conversation to %s", backup_path)
             except Exception as backup_error:  # pragma: no cover
                 logger.warning("Failed to backup corrupted file: %s", backup_error)
@@ -105,11 +113,12 @@ class ConversationManager:
             )
             return None
 
-    def clear(self) -> None:
+    async def clear(self) -> None:
         """Delete the conversation history file."""
-        if self.conversation_path.exists():
+        if await aiofiles.os.path.exists(self.conversation_path):
             try:
-                self.conversation_path.unlink()
+                # Use asyncio.to_thread for unlink operation
+                await asyncio.to_thread(self.conversation_path.unlink)
                 logger.debug(
                     "Conversation history cleared at %s", self.conversation_path
                 )

shotgun/agents/export.py

@@ -23,7 +23,7 @@ from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 logger = get_logger(__name__)
 
 
-def create_export_agent(
+async def create_export_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
 ) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create an export agent with file management capabilities.
@@ -39,7 +39,7 @@ def create_export_agent(
     # Use partial to create system prompt function for export agent
     system_prompt_fn = partial(build_agent_system_prompt, "export")
 
-    agent, deps = create_base_agent(
+    agent, deps = await create_base_agent(
         system_prompt_fn,
         agent_runtime_options,
         provider=provider,

shotgun/agents/history/token_counting/anthropic.py

@@ -72,11 +72,23 @@ class AnthropicTokenCounter(TokenCounter):
         Raises:
             RuntimeError: If API call fails
         """
+        # Handle empty text to avoid unnecessary API calls
+        # Anthropic API requires non-empty content, so we need a strict check
+        if not text or not text.strip():
+            return 0
+
+        # Additional validation: ensure the text has actual content
+        # Some edge cases might have only whitespace or control characters
+        cleaned_text = text.strip()
+        if not cleaned_text:
+            return 0
+
         try:
             # Anthropic API expects messages format and model parameter
             # Use await with async client
             result = await self.client.messages.count_tokens(
-                messages=[{"role": "user", "content": text}], model=self.model_name
+                messages=[{"role": "user", "content": cleaned_text}],
+                model=self.model_name,
             )
             return result.input_tokens
         except Exception as e:
@@ -107,5 +119,9 @@ class AnthropicTokenCounter(TokenCounter):
         Raises:
             RuntimeError: If token counting fails
         """
+        # Handle empty message list early
+        if not messages:
+            return 0
+
         total_text = extract_text_from_messages(messages)
         return await self.count_tokens(total_text)

shotgun/agents/history/token_counting/base.py

@@ -56,12 +56,23 @@ def extract_text_from_messages(messages: list[ModelMessage]) -> str:
         if hasattr(message, "parts"):
             for part in message.parts:
                 if hasattr(part, "content") and isinstance(part.content, str):
-                    text_parts.append(part.content)
+                    # Only add non-empty content
+                    if part.content.strip():
+                        text_parts.append(part.content)
                 else:
                     # Handle non-text parts (tool calls, etc.)
-                    text_parts.append(str(part))
+                    part_str = str(part)
+                    if part_str.strip():
+                        text_parts.append(part_str)
         else:
             # Handle messages without parts
-            text_parts.append(str(message))
+            msg_str = str(message)
+            if msg_str.strip():
+                text_parts.append(msg_str)
+
+    # If no valid text parts found, return a minimal placeholder
+    # This ensures we never send completely empty content to APIs
+    if not text_parts:
+        return "."
 
     return "\n".join(text_parts)

shotgun/agents/history/token_counting/openai.py

@@ -57,6 +57,10 @@ class OpenAITokenCounter(TokenCounter):
         Raises:
             RuntimeError: If token counting fails
         """
+        # Handle empty text to avoid unnecessary encoding
+        if not text or not text.strip():
+            return 0
+
         try:
             return len(self.encoding.encode(text))
         except Exception as e:
@@ -76,5 +80,9 @@ class OpenAITokenCounter(TokenCounter):
         Raises:
             RuntimeError: If token counting fails
         """
+        # Handle empty message list early
+        if not messages:
+            return 0
+
         total_text = extract_text_from_messages(messages)
         return await self.count_tokens(total_text)

shotgun/agents/history/token_counting/sentencepiece_counter.py

@@ -88,6 +88,10 @@ class SentencePieceTokenCounter(TokenCounter):
         Raises:
             RuntimeError: If token counting fails
         """
+        # Handle empty text to avoid unnecessary tokenization
+        if not text or not text.strip():
+            return 0
+
         await self._ensure_tokenizer()
 
         if self.sp is None:
@@ -115,5 +119,9 @@ class SentencePieceTokenCounter(TokenCounter):
         Raises:
             RuntimeError: If token counting fails
         """
+        # Handle empty message list early
+        if not messages:
+            return 0
+
         total_text = extract_text_from_messages(messages)
         return await self.count_tokens(total_text)

shotgun/agents/history/token_counting/tokenizer_cache.py

@@ -3,6 +3,7 @@
 import hashlib
 from pathlib import Path
 
+import aiofiles
 import httpx
 
 from shotgun.logging_config import get_logger
@@ -78,7 +79,8 @@ async def download_gemini_tokenizer() -> Path:
 
         # Atomic write: write to temp file first, then rename
         temp_path = cache_path.with_suffix(".tmp")
-        temp_path.write_bytes(content)
+        async with aiofiles.open(temp_path, "wb") as f:
+            await f.write(content)
         temp_path.rename(cache_path)
 
         logger.info(f"Gemini tokenizer downloaded and cached at {cache_path}")

shotgun/agents/history/token_counting/utils.py

@@ -44,9 +44,6 @@ def get_token_counter(model_config: ModelConfig) -> TokenCounter:
 
     # Return cached instance if available
     if cache_key in _token_counter_cache:
-        logger.debug(
-            f"Reusing cached token counter for {model_config.provider.value}:{model_config.name}"
-        )
         return _token_counter_cache[cache_key]
 
     # Create new instance and cache it

shotgun/agents/plan.py

@@ -23,7 +23,7 @@ from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 logger = get_logger(__name__)
 
 
-def create_plan_agent(
+async def create_plan_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
 ) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a plan agent with artifact management capabilities.
@@ -39,7 +39,7 @@ def create_plan_agent(
     # Use partial to create system prompt function for plan agent
     system_prompt_fn = partial(build_agent_system_prompt, "plan")
 
-    agent, deps = create_base_agent(
+    agent, deps = await create_base_agent(
         system_prompt_fn,
         agent_runtime_options,
         load_codebase_understanding_tools=True,

shotgun/agents/research.py

@@ -26,7 +26,7 @@ from .tools import get_available_web_search_tools
 logger = get_logger(__name__)
 
 
-def create_research_agent(
+async def create_research_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
 ) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a research agent with web search and artifact management capabilities.
@@ -41,7 +41,7 @@ def create_research_agent(
     logger.debug("Initializing research agent")
 
     # Get available web search tools based on configured API keys
-    web_search_tools = get_available_web_search_tools()
+    web_search_tools = await get_available_web_search_tools()
     if web_search_tools:
         logger.info(
             "Research agent configured with %d web search tool(s)",
@@ -53,7 +53,7 @@ def create_research_agent(
     # Use partial to create system prompt function for research agent
     system_prompt_fn = partial(build_agent_system_prompt, "research")
 
-    agent, deps = create_base_agent(
+    agent, deps = await create_base_agent(
         system_prompt_fn,
         agent_runtime_options,
         load_codebase_understanding_tools=True,

shotgun/agents/specify.py

@@ -23,7 +23,7 @@ from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 logger = get_logger(__name__)
 
 
-def create_specify_agent(
+async def create_specify_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
 ) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a specify agent with artifact management capabilities.
@@ -39,7 +39,7 @@ def create_specify_agent(
     # Use partial to create system prompt function for specify agent
     system_prompt_fn = partial(build_agent_system_prompt, "specify")
 
-    agent, deps = create_base_agent(
+    agent, deps = await create_base_agent(
         system_prompt_fn,
         agent_runtime_options,
         load_codebase_understanding_tools=True,

shotgun/agents/tasks.py

@@ -23,7 +23,7 @@ from .models import AgentDeps, AgentResponse, AgentRuntimeOptions, AgentType
 logger = get_logger(__name__)
 
 
-def create_tasks_agent(
+async def create_tasks_agent(
     agent_runtime_options: AgentRuntimeOptions, provider: ProviderType | None = None
 ) -> tuple[Agent[AgentDeps, AgentResponse], AgentDeps]:
     """Create a tasks agent with file management capabilities.
@@ -39,7 +39,7 @@ def create_tasks_agent(
     # Use partial to create system prompt function for tasks agent
     system_prompt_fn = partial(build_agent_system_prompt, "tasks")
 
-    agent, deps = create_base_agent(
+    agent, deps = await create_base_agent(
         system_prompt_fn,
         agent_runtime_options,
         provider=provider,

shotgun/agents/tools/codebase/file_read.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 
+import aiofiles
 from pydantic_ai import RunContext
 
 from shotgun.agents.models import AgentDeps
@@ -93,7 +94,8 @@ async def file_read(
         # Read file contents
         encoding_used = "utf-8"
         try:
-            content = full_file_path.read_text(encoding="utf-8")
+            async with aiofiles.open(full_file_path, encoding="utf-8") as f:
+                content = await f.read()
             size_bytes = full_file_path.stat().st_size
 
             logger.debug(
@@ -119,7 +121,8 @@ async def file_read(
             try:
                 # Try with different encoding
                 encoding_used = "latin-1"
-                content = full_file_path.read_text(encoding="latin-1")
+                async with aiofiles.open(full_file_path, encoding="latin-1") as f:
+                    content = await f.read()
                 size_bytes = full_file_path.stat().st_size
 
                 # Detect language from file extension

shotgun/agents/tools/file_management.py

@@ -6,6 +6,8 @@ These tools are restricted to the .shotgun directory for security.
 from pathlib import Path
 from typing import Literal
 
+import aiofiles
+import aiofiles.os
 from pydantic_ai import RunContext
 
 from shotgun.agents.models import AgentDeps, AgentType, FileOperationType
@@ -181,10 +183,11 @@ async def read_file(ctx: RunContext[AgentDeps], filename: str) -> str:
     try:
         file_path = _validate_shotgun_path(filename)
 
-        if not file_path.exists():
+        if not await aiofiles.os.path.exists(file_path):
             raise FileNotFoundError(f"File not found: {filename}")
 
-        content = file_path.read_text(encoding="utf-8")
+        async with aiofiles.open(file_path, encoding="utf-8") as f:
+            content = await f.read()
         logger.debug("📄 Read %d characters from %s", len(content), filename)
         return content
 
@@ -233,21 +236,22 @@ async def write_file(
         else:
             operation = (
                 FileOperationType.CREATED
-                if not file_path.exists()
+                if not await aiofiles.os.path.exists(file_path)
                 else FileOperationType.UPDATED
             )
 
         # Ensure parent directory exists
-        file_path.parent.mkdir(parents=True, exist_ok=True)
+        await aiofiles.os.makedirs(file_path.parent, exist_ok=True)
 
         # Write content
         if mode == "a":
-            with open(file_path, "a", encoding="utf-8") as f:
-                f.write(content)
+            async with aiofiles.open(file_path, "a", encoding="utf-8") as f:
+                await f.write(content)
             logger.debug("📄 Appended %d characters to %s", len(content), filename)
             result = f"Successfully appended {len(content)} characters to {filename}"
         else:
-            file_path.write_text(content, encoding="utf-8")
+            async with aiofiles.open(file_path, "w", encoding="utf-8") as f:
+                await f.write(content)
             logger.debug("📄 Wrote %d characters to %s", len(content), filename)
             result = f"Successfully wrote {len(content)} characters to {filename}"
 

shotgun/agents/tools/web_search/__init__.py

@@ -26,7 +26,7 @@ logger = get_logger(__name__)
 WebSearchTool = Callable[[str], Awaitable[str]]
 
 
-def get_available_web_search_tools() -> list[WebSearchTool]:
+async def get_available_web_search_tools() -> list[WebSearchTool]:
     """Get list of available web search tools based on configured API keys.
 
     Works with both Shotgun Account (via LiteLLM proxy) and BYOK (individual provider keys).
@@ -43,25 +43,25 @@ def get_available_web_search_tools() -> list[WebSearchTool]:
 
     # Check if using Shotgun Account
     config_manager = get_config_manager()
-    config = config_manager.load()
+    config = await config_manager.load()
     has_shotgun_key = config.shotgun.api_key is not None
 
     if has_shotgun_key:
         logger.debug("🔑 Shotgun Account - only Gemini web search available")
 
         # Gemini: Only search tool available for Shotgun Account
-        if is_provider_available(ProviderType.GOOGLE):
+        if await is_provider_available(ProviderType.GOOGLE):
             logger.debug("✅ Gemini web search tool available")
             tools.append(gemini_web_search_tool)
 
         # Anthropic: Not available for Shotgun Account (Gemini-only for Shotgun)
-        if is_provider_available(ProviderType.ANTHROPIC):
+        if await is_provider_available(ProviderType.ANTHROPIC):
             logger.debug(
                 "⚠️  Anthropic web search requires BYOK (Shotgun Account uses Gemini only)"
             )
 
         # OpenAI: Not available for Shotgun Account (Responses API incompatible with proxy)
-        if is_provider_available(ProviderType.OPENAI):
+        if await is_provider_available(ProviderType.OPENAI):
             logger.debug(
                 "⚠️  OpenAI web search requires BYOK (Responses API not supported via proxy)"
             )
@@ -69,15 +69,15 @@ def get_available_web_search_tools() -> list[WebSearchTool]:
         # BYOK mode: Load all available tools based on individual provider keys
         logger.debug("🔑 BYOK mode - checking all provider web search tools")
 
-        if is_provider_available(ProviderType.OPENAI):
+        if await is_provider_available(ProviderType.OPENAI):
             logger.debug("✅ OpenAI web search tool available")
             tools.append(openai_web_search_tool)
 
-        if is_provider_available(ProviderType.ANTHROPIC):
+        if await is_provider_available(ProviderType.ANTHROPIC):
             logger.debug("✅ Anthropic web search tool available")
             tools.append(anthropic_web_search_tool)
 
-        if is_provider_available(ProviderType.GOOGLE):
+        if await is_provider_available(ProviderType.GOOGLE):
             logger.debug("✅ Gemini web search tool available")
             tools.append(gemini_web_search_tool)
 

shotgun/agents/tools/web_search/anthropic.py

@@ -46,7 +46,7 @@ async def anthropic_web_search_tool(query: str) -> str:
 
     # Get model configuration (supports both Shotgun and BYOK)
     try:
-        model_config = get_provider_model(ProviderType.ANTHROPIC)
+        model_config = await get_provider_model(ProviderType.ANTHROPIC)
     except ValueError as e:
         error_msg = f"Anthropic API key not configured: {str(e)}"
         logger.error("❌ %s", error_msg)
@@ -141,7 +141,7 @@ async def main() -> None:
     # Check if API key is available
     try:
         if callable(get_provider_model):
-            model_config = get_provider_model(ProviderType.ANTHROPIC)
+            model_config = await get_provider_model(ProviderType.ANTHROPIC)
             if not model_config.api_key:
                 raise ValueError("No API key configured")
     except (ValueError, Exception):

shotgun/agents/tools/web_search/gemini.py

@@ -46,7 +46,7 @@ async def gemini_web_search_tool(query: str) -> str:
 
     # Get model configuration (supports both Shotgun and BYOK)
     try:
-        model_config = get_provider_model(ModelName.GEMINI_2_5_FLASH)
+        model_config = await get_provider_model(ModelName.GEMINI_2_5_FLASH)
     except ValueError as e:
         error_msg = f"Gemini API key not configured: {str(e)}"
         logger.error("❌ %s", error_msg)

shotgun/agents/tools/web_search/openai.py

@@ -43,7 +43,7 @@ async def openai_web_search_tool(query: str) -> str:
 
         # Get API key from centralized configuration
         try:
-            model_config = get_provider_model(ProviderType.OPENAI)
+            model_config = await get_provider_model(ProviderType.OPENAI)
             api_key = model_config.api_key
         except ValueError as e:
             error_msg = f"OpenAI API key not configured: {str(e)}"

shotgun/agents/tools/web_search/utils.py

@@ -4,7 +4,7 @@ from shotgun.agents.config import get_provider_model
 from shotgun.agents.config.models import ProviderType
 
 
-def is_provider_available(provider: ProviderType) -> bool:
+async def is_provider_available(provider: ProviderType) -> bool:
     """Check if a provider has API key configured.
 
     Args:
@@ -14,7 +14,7 @@ def is_provider_available(provider: ProviderType) -> bool:
         True if the provider has valid credentials configured (from config or env)
     """
     try:
-        get_provider_model(provider)
+        await get_provider_model(provider)
         return True
     except ValueError:
         return False

shotgun/agents/usage_manager.py

@@ -6,6 +6,8 @@ from logging import getLogger
 from pathlib import Path
 from typing import TypeAlias
 
+import aiofiles
+import aiofiles.os
 from genai_prices import calc_price
 from pydantic import BaseModel, Field
 from pydantic_ai import RunUsage
@@ -48,9 +50,10 @@ class SessionUsageManager:
         self._model_providers: dict[ModelName, ProviderType] = {}
         self._usage_log: list[UsageLogEntry] = []
         self._usage_path: Path = get_shotgun_home() / "usage.json"
-        self.restore_usage_state()
+        # Note: restore_usage_state needs to be called asynchronously after init
+        # Caller should use: manager = SessionUsageManager(); await manager.restore_usage_state()
 
-    def add_usage(
+    async def add_usage(
         self, usage: RunUsage, *, model_name: ModelName, provider: ProviderType
     ) -> None:
         self.usage[model_name] += usage
@@ -58,7 +61,7 @@ class SessionUsageManager:
         self._usage_log.append(
             UsageLogEntry(model_name=model_name, usage=usage, provider=provider)
         )
-        self.persist_usage_state()
+        await self.persist_usage_state()
 
     def get_usage_report(self) -> dict[ModelName, RunUsage]:
         return self.usage.copy()
@@ -78,7 +81,7 @@ class SessionUsageManager:
     def build_usage_hint(self) -> str | None:
         return format_usage_hint(self.get_usage_breakdown())
 
-    def persist_usage_state(self) -> None:
+    async def persist_usage_state(self) -> None:
         state = UsageState(
             usage=dict(self.usage.items()),
             model_providers=self._model_providers.copy(),
@@ -86,23 +89,25 @@ class SessionUsageManager:
         )
 
         try:
-            self._usage_path.parent.mkdir(parents=True, exist_ok=True)
-            with self._usage_path.open("w", encoding="utf-8") as f:
-                json.dump(state.model_dump(mode="json"), f, indent=2)
+            await aiofiles.os.makedirs(self._usage_path.parent, exist_ok=True)
+            json_content = json.dumps(state.model_dump(mode="json"), indent=2)
+            async with aiofiles.open(self._usage_path, "w", encoding="utf-8") as f:
+                await f.write(json_content)
             logger.debug("Usage state persisted to %s", self._usage_path)
         except Exception as exc:
             logger.error(
                 "Failed to persist usage state to %s: %s", self._usage_path, exc
             )
 
-    def restore_usage_state(self) -> None:
-        if not self._usage_path.exists():
+    async def restore_usage_state(self) -> None:
+        if not await aiofiles.os.path.exists(self._usage_path):
             logger.debug("No usage state file found at %s", self._usage_path)
             return
 
         try:
-            with self._usage_path.open(encoding="utf-8") as f:
-                data = json.load(f)
+            async with aiofiles.open(self._usage_path, encoding="utf-8") as f:
+                content = await f.read()
+                data = json.loads(content)
 
             state = UsageState.model_validate(data)
         except Exception as exc: