feat: implement skeleton phase

src/beaver_gateway/agents/__init__.py

@@ -0,0 +1,9 @@
+"""Agent type definitions exposed to user config."""
+
+from __future__ import annotations
+
+from beaver_gateway.agents.base import BaseAgent, ExposedMcp
+from beaver_gateway.agents.claude import ClaudeAgent
+from beaver_gateway.agents.raycast import RaycastAgent
+
+__all__ = ["BaseAgent", "ClaudeAgent", "ExposedMcp", "RaycastAgent"]

src/beaver_gateway/agents/base.py

@@ -0,0 +1,33 @@
+"""Shared agent surface.
+
+``BaseAgent`` is the structural contract every backend-specific agent
+honours. Subclasses add **capabilities as fields** (``ClaudeAgent.cwd``,
+``RaycastAgent.streaming``) — backends dispatch on type, not on a runtime
+matrix.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel, ConfigDict
+
+
+@dataclass(frozen=True, slots=True)
+class ExposedMcp:
+    """Reference to an ``McpServer`` (by name) exposed to a single agent."""
+
+    name: str
+    tools: tuple[str, ...] | None = None
+
+
+class BaseAgent(BaseModel):
+    """Common fields. Concrete backends subclass and add capabilities."""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    name: str
+    model: str
+    system_prompt: str
+    expose_mcps: tuple[ExposedMcp, ...] = ()
+    accept_client_tools: bool = False

src/beaver_gateway/agents/claude.py

@@ -0,0 +1,17 @@
+"""Claude Code agent definition.
+
+Notice the absence of a ``streaming`` field — claude-code does not emit
+token-level deltas, and that fact is encoded in the type, not in a
+runtime branch.
+"""
+
+from __future__ import annotations
+
+from beaver_gateway.agents.base import BaseAgent
+
+
+class ClaudeAgent(BaseAgent):
+    """Agent backed by ``claude-code-api``."""
+
+    cwd: str
+    available_native_tools: tuple[str, ...] = ()

src/beaver_gateway/agents/raycast.py

@@ -0,0 +1,15 @@
+"""Raycast agent definition."""
+
+from __future__ import annotations
+
+from raycast_api import Source
+
+from beaver_gateway.agents.base import BaseAgent
+
+
+class RaycastAgent(BaseAgent):
+    """Agent backed by ``raycast-api``."""
+
+    streaming: bool = True
+    available_native_tools: tuple[str, ...] = ()
+    source: Source = Source.AI_CHAT