steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/events.py

@@ -0,0 +1,294 @@
+"""Events streaming API client with batching support."""
+
+import asyncio
+import contextlib
+from datetime import UTC, datetime
+from typing import Any, Self
+
+import httpx
+from loguru import logger
+from pydantic import BaseModel, Field
+
+from steerdev_agent.api.client import get_api_endpoint, get_api_key
+
+
+class EventData(BaseModel):
+    """Model for a single event to be sent to the API."""
+
+    event_type: str = Field(description="Type of event (e.g., assistant, user, system, tool_use)")
+    event_timestamp: str = Field(description="ISO timestamp of when the event occurred")
+    data: dict[str, Any] = Field(description="Structured event data")
+    raw_json: str = Field(description="Original raw JSON from the agent")
+
+
+class EventBatchRequest(BaseModel):
+    """Request model for batch inserting events."""
+
+    events: list[EventData] = Field(description="List of events to insert")
+
+
+class EventResponse(BaseModel):
+    """Response model for an event."""
+
+    id: str
+    session_id: str
+    event_type: str
+    event_timestamp: str
+    data: dict[str, Any]
+    raw_json: str
+    created_at: str
+
+
+class EventListResponse(BaseModel):
+    """Response model for listing events."""
+
+    events: list[EventResponse]
+    total: int
+
+
+class EventsClient:
+    """Async HTTP client for Events API with batching support.
+
+    Buffers events and sends them in batches to reduce API calls.
+    Configurable batch size and flush interval.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        batch_size: int = 10,
+        flush_interval_seconds: float = 5.0,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            session_id: Session ID to associate events with.
+            api_key: API key for authentication. If not provided, reads from STEERDEV_API_KEY.
+            timeout: Request timeout in seconds.
+            batch_size: Number of events to buffer before auto-flushing.
+            flush_interval_seconds: Maximum time to wait before flushing events.
+        """
+        self.session_id = session_id
+        self.api_key = api_key or get_api_key()
+        self.api_base = get_api_endpoint()
+        self.timeout = timeout
+        self.batch_size = batch_size
+        self.flush_interval_seconds = flush_interval_seconds
+
+        self._client: httpx.AsyncClient | None = None
+        self._buffer: list[EventData] = []
+        self._buffer_lock = asyncio.Lock()
+        self._flush_task: asyncio.Task[None] | None = None
+        self._running = False
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """Get request headers with authentication."""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create async HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        return self._client
+
+    async def start(self) -> None:
+        """Start the background flush task."""
+        if self._running:
+            return
+
+        self._running = True
+        self._flush_task = asyncio.create_task(self._flush_loop())
+        logger.debug(f"EventsClient started for session {self.session_id}")
+
+    async def stop(self) -> None:
+        """Stop the background flush task and flush remaining events."""
+        self._running = False
+
+        if self._flush_task:
+            self._flush_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._flush_task
+            self._flush_task = None
+
+        # Final flush
+        await self.flush()
+        logger.debug(f"EventsClient stopped for session {self.session_id}")
+
+    async def close(self) -> None:
+        """Stop and close the HTTP client."""
+        await self.stop()
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> Self:
+        """Enter async context manager."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit async context manager."""
+        await self.close()
+
+    async def _flush_loop(self) -> None:
+        """Background task that periodically flushes events."""
+        while self._running:
+            try:
+                await asyncio.sleep(self.flush_interval_seconds)
+                await self.flush()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Error in flush loop: {e}")
+
+    async def add_event(
+        self,
+        event_type: str,
+        data: dict[str, Any],
+        raw_json: str,
+        timestamp: datetime | None = None,
+    ) -> None:
+        """Add an event to the buffer.
+
+        Events are automatically flushed when the batch size is reached
+        or when the flush interval expires.
+
+        Args:
+            event_type: Type of event (e.g., assistant, user, system).
+            data: Structured event data.
+            raw_json: Original raw JSON string.
+            timestamp: Event timestamp. Defaults to now.
+        """
+        if timestamp is None:
+            timestamp = datetime.now(UTC)
+
+        event = EventData(
+            event_type=event_type,
+            event_timestamp=timestamp.isoformat(),
+            data=data,
+            raw_json=raw_json,
+        )
+
+        async with self._buffer_lock:
+            self._buffer.append(event)
+            buffer_size = len(self._buffer)
+
+        # Auto-flush if batch size reached
+        if buffer_size >= self.batch_size:
+            await self.flush()
+
+    async def flush(self) -> bool:
+        """Flush buffered events to the API.
+
+        Returns:
+            True if flush succeeded or no events to flush, False on error.
+        """
+        async with self._buffer_lock:
+            if not self._buffer:
+                return True
+
+            events_to_send = self._buffer.copy()
+            self._buffer.clear()
+
+        logger.debug(f"Flushing {len(events_to_send)} events for session {self.session_id}")
+
+        client = await self._get_client()
+        request = EventBatchRequest(events=events_to_send)
+        url = f"{self.api_base}/sessions/{self.session_id}/events"
+
+        try:
+            logger.debug(f"POST {url}")
+            response = await client.post(
+                url,
+                headers=self.headers,
+                json=request.model_dump(),
+            )
+
+            if response.status_code in (200, 201):
+                logger.debug(f"Successfully flushed {len(events_to_send)} events")
+                return True
+
+            logger.error(f"Failed to flush events to {url}: {response.status_code} - {response.text[:200]}")
+            # Re-add events to buffer on failure
+            async with self._buffer_lock:
+                self._buffer = events_to_send + self._buffer
+            return False
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error flushing events to {url}: {e}")
+            # Re-add events to buffer on failure
+            async with self._buffer_lock:
+                self._buffer = events_to_send + self._buffer
+            return False
+
+    async def get_events(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> EventListResponse | None:
+        """Get events for the session (for debugging).
+
+        Args:
+            limit: Maximum number of events to return.
+            offset: Offset for pagination.
+
+        Returns:
+            Event list response or None on failure.
+        """
+        client = await self._get_client()
+        params: dict[str, int] = {"limit": limit, "offset": offset}
+
+        logger.debug(f"Getting events for session {self.session_id}")
+
+        try:
+            response = await client.get(
+                f"{self.api_base}/sessions/{self.session_id}/events",
+                headers=self.headers,
+                params=params,
+            )
+
+            if response.status_code == 200:
+                return EventListResponse(**response.json())
+
+            logger.error(f"Failed to get events: {response.status_code} - {response.text}")
+            return None
+
+        except httpx.RequestError as e:
+            logger.error(f"Request error getting events: {e}")
+            return None
+
+    @property
+    def pending_events(self) -> int:
+        """Return the number of events pending in the buffer."""
+        return len(self._buffer)
+
+
+def create_event_from_stream(
+    event_type: str,
+    message_data: dict[str, Any],
+    raw_json: str,
+) -> EventData:
+    """Create an EventData from stream output.
+
+    Helper function to create events from Claude's stream-json output.
+
+    Args:
+        event_type: The type from Claude's stream (assistant, user, system, etc.).
+        message_data: The parsed message data.
+        raw_json: The original raw JSON line.
+
+    Returns:
+        EventData ready to be added to the client.
+    """
+    return EventData(
+        event_type=event_type,
+        event_timestamp=datetime.now(UTC).isoformat(),
+        data=message_data,
+        raw_json=raw_json,
+    )

steerdev_agent/api/hooks.py

@@ -0,0 +1,178 @@
+"""Claude Code hooks API client for activity reporting."""
+
+import json
+import os
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+
+from steerdev_agent.api.client import get_agent_name, get_api_key
+
+# Default activity API endpoint
+DEFAULT_ACTIVITY_ENDPOINT = "https://steerdev.com/api/v1"
+
+
+def get_activity_endpoint() -> str:
+    """Get activity API endpoint from environment or use default."""
+    return os.environ.get("STEERDEV_API_ENDPOINT", DEFAULT_ACTIVITY_ENDPOINT)
+
+
+class HooksClient:
+    """Client for reporting hook events to SteerDev activity API.
+
+    Hooks read JSON input from stdin (provided by Claude Code) and
+    report activity events to the SteerDev platform.
+    """
+
+    def __init__(self, timeout: float = 5.0) -> None:
+        """Initialize the hooks client.
+
+        Args:
+            timeout: Request timeout in seconds (short for hooks).
+        """
+        self.api_key = get_api_key()
+        self.api_endpoint = get_activity_endpoint()
+        self.timeout = timeout
+        self.agent_name = get_agent_name()
+
+    def read_stdin_input(self) -> dict[str, Any] | None:
+        """Read JSON input from stdin.
+
+        Returns:
+            Parsed JSON dict or None on failure.
+        """
+        try:
+            return json.load(sys.stdin)
+        except json.JSONDecodeError:
+            return None
+
+    def report_event(
+        self,
+        event_type: str,
+        input_data: dict[str, Any],
+        extra_metadata: dict[str, Any] | None = None,
+    ) -> bool:
+        """Report an activity event to the SteerDev API.
+
+        Args:
+            event_type: Type of event (e.g., "session_start", "agent_stopped").
+            input_data: Input data from Claude Code hook.
+            extra_metadata: Additional metadata to include.
+
+        Returns:
+            True if the event was reported successfully.
+        """
+        if not self.api_key:
+            return False
+
+        # Build base metadata
+        metadata: dict[str, Any] = {
+            "cwd": input_data.get("cwd"),
+            "transcript_path": input_data.get("transcript_path"),
+            "permission_mode": input_data.get("permission_mode"),
+        }
+
+        # Add extra metadata
+        if extra_metadata:
+            metadata.update(extra_metadata)
+
+        # Build event payload
+        event = {
+            "event_type": event_type,
+            "timestamp": datetime.now(UTC).isoformat(),
+            "session_name": input_data.get("session_id"),
+            "metadata": metadata,
+        }
+
+        # Build request body
+        request_body = {
+            "agent_name": self.agent_name,
+            "application": "claude_code",
+            "events": [event],
+        }
+
+        # Send to API (non-blocking)
+        try:
+            httpx.post(
+                f"{self.api_endpoint}/activity/report",
+                json=request_body,
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=self.timeout,
+            )
+            return True
+        except Exception:
+            return False
+
+    def session_start(self) -> None:
+        """Process SessionStart hook event.
+
+        Reads JSON from stdin and reports session_start event.
+        """
+        input_data = self.read_stdin_input()
+        if not input_data:
+            sys.exit(0)
+
+        self.report_event(
+            event_type="session_start",
+            input_data=input_data,
+            extra_metadata={
+                "source": input_data.get("source"),  # startup, resume, clear, compact
+            },
+        )
+        sys.exit(0)
+
+    def session_end(self) -> None:
+        """Process SessionEnd hook event.
+
+        Reads JSON from stdin and reports session_end event.
+        """
+        input_data = self.read_stdin_input()
+        if not input_data:
+            sys.exit(0)
+
+        self.report_event(
+            event_type="session_end",
+            input_data=input_data,
+            extra_metadata={
+                "reason": input_data.get("reason"),  # clear, logout, prompt_input_exit, other
+            },
+        )
+        sys.exit(0)
+
+    def agent_stop(self) -> None:
+        """Process Stop hook event (main agent).
+
+        Reads JSON from stdin and reports agent_stopped event.
+        """
+        input_data = self.read_stdin_input()
+        if not input_data:
+            sys.exit(0)
+
+        self.report_event(
+            event_type="agent_stopped",
+            input_data=input_data,
+            extra_metadata={
+                "stop_hook_active": input_data.get("stop_hook_active"),
+            },
+        )
+        sys.exit(0)
+
+    def subagent_stop(self) -> None:
+        """Process SubagentStop hook event.
+
+        Reads JSON from stdin and reports subagent_stopped event.
+        """
+        input_data = self.read_stdin_input()
+        if not input_data:
+            sys.exit(0)
+
+        self.report_event(
+            event_type="subagent_stopped",
+            input_data=input_data,
+            extra_metadata={
+                "stop_hook_active": input_data.get("stop_hook_active"),
+            },
+        )
+        sys.exit(0)