feat: implement raycast backend

src/beaver_gateway/agents/raycast.py

@@ -1,15 +1,79 @@
-"""Raycast agent definition."""
+"""Raycast agent definition.
+
+Field set is the union of ``raycast_api.ChatAPI.stream`` parameters that
+make sense as **per-agent defaults**. Per-request values (currently:
+``temperature``) win when both are set; the rest fall back to whatever
+the agent declared, then to Raycast's own defaults.
+
+``BaseAgent.system_prompt`` maps onto Raycast's wire field
+``additional_system_instructions`` (the slot the real client uses for
+*content*); the wire field ``system_instructions`` stays at the Raycast
+source default — ``"markdown"`` for ``AI_CHAT``, ``"plain"`` otherwise.
+We don't expose that wire dichotomy to the user — they get one
+conceptual "system prompt".
+
+Excluded on purpose:
+
+* ``buffer_id``/``message_id``/``current_date`` — per-call ephemeral
+* ``provider`` override — escape hatch for non-catalog models, no clear
+  use case yet (revisit in PRD §14 when discovery lands)
+* ``locale`` — process-wide via ``Settings.raycast_locale`` because we
+  only spin up one ``raycast_api.Client`` per gateway
+* ``system_instructions`` (wire) — that's a format marker, not content;
+  the SDK fills it from the source default and we let it
+"""
 
 from __future__ import annotations
 
-from raycast_api import Source
+from raycast_api import (  # noqa: F401  — UserPreferences re-exported for user configs
+    RemoteTool,
+    Source,
+    UserPreferences,
+    UserPreferencesArg,
+)
 
 from beaver_gateway.agents.base import BaseAgent
 
 
 class RaycastAgent(BaseAgent):
-    """Agent backed by ``raycast-api``."""
+    """Agent backed by ``raycast-api``.
+
+    ``available_native_tools`` is the closed set of Raycast's server-side
+    "remote tools" (``web_search``, ``search_images``, ``read_page``) —
+    typed as ``RemoteTool`` so config-time IDE completion lists exactly
+    the three valid values. Pydantic also coerces string literals, so
+    ``("web_search", "read_page")`` keeps working unchanged.
+
+    ``user_preferences`` toggles the auto-generated ``<user-preferences>``
+    block Raycast prepends to ``additional_system_instructions``:
+
+    * ``True`` (default) → auto from host locale/timezone/today, rebuilt
+      every request so the date stays fresh;
+    * ``False`` → omit the block entirely;
+    * ``UserPreferences(...)`` instance → used verbatim (frozen at the
+      time the agent was loaded, so the date won't auto-update);
+    * ``Callable[[], UserPreferencesArg]`` → re-invoked on every request.
+      Use this for the common case "fresh date but custom
+      locale/timezone": ``user_preferences=lambda:
+      UserPreferences(locale="ru-RU", timezone="Europe/Berlin",
+      current_date=date.today().isoformat())``. Callables may nest
+      (a lambda returning a lambda…) but there's no real reason to.
+
+    The library uses this block for date/locale-aware formatting, not
+    for personalisation/memory — those are out of scope upstream.
+
+    ``reasoning_effort`` values vary by model: GPT-5 takes
+    ``"minimal"|"low"|"medium"|"high"``; Anthropic exposes nothing here
+    (Claude reasoning lives in a separate ``…-reasoning`` model variant
+    in the catalog). Unknown effort for the chosen model is ignored
+    server-side, so we stay loose as ``str | None``.
+    """
 
     streaming: bool = True
-    available_native_tools: tuple[str, ...] = ()
+    available_native_tools: tuple[RemoteTool, ...] = ()
     source: Source = Source.AI_CHAT
+
+    temperature: float | None = None
+    reasoning_effort: str | None = None
+    tool_choice: str | None = None
+    user_preferences: UserPreferencesArg = True