Phase 2: BaseTool + MailAPI with 3 drift handlers

tests/test_mail.py

@@ -0,0 +1,149 @@
+"""MailAPI + BaseTool acceptance tests — Phase 2."""
+from __future__ import annotations
+
+from models import DriftEvent
+from tools.mail import MailAPI
+
+
+def _fresh_mail() -> MailAPI:
+    seed = {
+        "messages": [
+            {"id": "msg_1", "from": "a@x.com", "to": "u@org.com",
+             "subject": "hi", "body": "hello", "folder": "inbox"},
+            {"id": "msg_2", "from": "b@x.com", "to": "u@org.com",
+             "subject": "welcome", "body": "hi there", "folder": "inbox"},
+            {"id": "msg_3", "from": "c@x.com", "to": "u@org.com",
+             "subject": "fyi", "body": "fyi", "folder": "inbox"},
+        ]
+    }
+    return MailAPI(seed_data=seed)
+
+
+def test_baseline_list_messages() -> None:
+    mail = _fresh_mail()
+    resp = mail.call("list_messages", {"folder": "inbox"})
+    assert resp.ok is True
+    assert resp.status == 200
+    assert resp.body is not None
+    assert "messages" in resp.body
+    assert "next_page_token" in resp.body
+    assert len(resp.body["messages"]) == 3
+
+
+def test_baseline_send_message() -> None:
+    mail = _fresh_mail()
+    resp = mail.call(
+        "send_message",
+        {"to": "x@y.com", "subject": "Hello", "body": "Hi!"},
+    )
+    assert resp.ok is True
+    assert resp.status == 200
+    assert resp.body is not None
+    assert "message_id" in resp.body
+    assert "sent_at" in resp.body
+
+
+def test_missing_required_param() -> None:
+    mail = _fresh_mail()
+    resp = mail.call(
+        "send_message",
+        {"to": "x@y.com", "subject": "Hello"},  # body missing
+    )
+    assert resp.ok is False
+    assert resp.status == 400
+    assert resp.error is not None
+    assert "missing" in resp.error.lower()
+    assert "body" in resp.error
+
+
+def test_drift_field_rename_list_messages() -> None:
+    mail = _fresh_mail()
+    event = DriftEvent(
+        tool="mail",
+        endpoint="list_messages",
+        kind="field_rename",
+        fires_at_step=1,
+        details={"from": "messages", "to": "items"},
+    )
+    mail.apply_drift(event)
+    resp = mail.call("list_messages", {"folder": "inbox"})
+    assert resp.ok is True
+    assert resp.body is not None
+    assert "items" in resp.body
+    assert "next_cursor" in resp.body
+    assert "messages" not in resp.body
+    assert "next_page_token" not in resp.body
+
+
+def test_drift_endpoint_deprecation() -> None:
+    mail = _fresh_mail()
+    event = DriftEvent(
+        tool="mail",
+        endpoint="send_message",
+        kind="endpoint_deprecation",
+        fires_at_step=1,
+        details={"replacement": "messages.send"},
+    )
+    mail.apply_drift(event)
+
+    old = mail.call(
+        "send_message",
+        {"to": "x@y.com", "subject": "Hi", "body": "Hi"},
+    )
+    assert old.ok is False
+    assert old.status == 410
+
+    new = mail.call(
+        "messages.send",
+        {"to": "x@y.com", "subject": "Hi", "body": "Hi"},
+    )
+    assert new.ok is True
+    assert new.status == 200
+    assert new.body is not None
+    assert "message_id" in new.body
+
+
+def test_drift_new_required_param() -> None:
+    mail = _fresh_mail()
+    event = DriftEvent(
+        tool="mail",
+        endpoint="send_message",
+        kind="new_required_param",
+        fires_at_step=1,
+        details={"param": "idempotency_key"},
+    )
+    mail.apply_drift(event)
+
+    without_key = mail.call(
+        "send_message",
+        {"to": "x@y.com", "subject": "Hi", "body": "Hi"},
+    )
+    assert without_key.ok is False
+    assert without_key.status == 400
+    assert without_key.error is not None
+    assert "idempotency_key" in without_key.error
+
+    with_key = mail.call(
+        "send_message",
+        {"to": "x@y.com", "subject": "Hi", "body": "Hi",
+         "idempotency_key": "k1"},
+    )
+    assert with_key.ok is True
+    assert with_key.status == 200
+
+
+def test_get_message_roundtrip() -> None:
+    mail = _fresh_mail()
+    sent = mail.call(
+        "send_message",
+        {"to": "x@y.com", "subject": "Hi", "body": "Hi there"},
+    )
+    assert sent.ok is True
+    assert sent.body is not None
+    mid = sent.body["message_id"]
+
+    got = mail.call("get_message", {"message_id": mid})
+    assert got.ok is True
+    assert got.status == 200
+    assert got.body is not None
+    assert got.body["id"] == mid

tools/base.py

@@ -1,4 +1,60 @@
-"""BaseTool + EndpointSchema — abstract contract for all SaaS tool APIs.
+"""BaseTool + EndpointSchema — abstract contract for all SaaS tool APIs."""
+from __future__ import annotations
 
-Will be filled in Phase 2.
-"""
+import copy
+from typing import Callable, Optional
+
+from pydantic import BaseModel
+
+from models import DriftEvent, ToolResponse
+
+
+class EndpointSchema(BaseModel):
+    name: str
+    params: dict[str, str]
+    required: list[str]
+    response_shape: dict[str, str]
+    error_codes: dict[int, str]
+
+
+class BaseTool:
+    name: str = ""
+    baseline_schemas: dict[str, EndpointSchema] = {}
+
+    def __init__(self) -> None:
+        self.active_schemas: dict[str, EndpointSchema] = copy.deepcopy(self.baseline_schemas)
+        self.handlers: dict[str, Callable[[dict], ToolResponse]] = {}
+
+    def get_schema(self, endpoint: Optional[str] = None) -> dict:
+        if endpoint is None:
+            return {k: v.model_dump() for k, v in self.active_schemas.items()}
+        if endpoint not in self.active_schemas:
+            return {}
+        return self.active_schemas[endpoint].model_dump()
+
+    def call(self, endpoint: str, params: dict) -> ToolResponse:
+        if endpoint not in self.active_schemas:
+            return ToolResponse(
+                ok=False,
+                status=410,
+                error=f"Endpoint '{endpoint}' is no longer available on {self.name}.",
+            )
+        schema = self.active_schemas[endpoint]
+        missing = [p for p in schema.required if p not in params]
+        if missing:
+            return ToolResponse(
+                ok=False,
+                status=400,
+                error=f"Missing required params: {missing}",
+            )
+        handler = self.handlers.get(endpoint)
+        if handler is None:
+            return ToolResponse(
+                ok=False,
+                status=501,
+                error=f"No handler registered for endpoint '{endpoint}' on {self.name}.",
+            )
+        return handler(params)
+
+    def apply_drift(self, event: DriftEvent) -> None:
+        raise NotImplementedError

tools/mail.py

@@ -1,4 +1,121 @@
-"""MailAPI — list_messages, send_message, get_message + 3 drift handlers.
+"""MailAPI — list_messages, send_message, get_message + 3 drift handlers."""
+from __future__ import annotations
 
-Will be filled in Phase 2.
-"""
+import copy
+
+from models import DriftEvent, ToolResponse
+from tools.base import BaseTool, EndpointSchema
+
+
+_LIST_MESSAGES_BASE = EndpointSchema(
+    name="list_messages",
+    params={"folder": "str", "limit": "int", "page_token": "str"},
+    required=["folder"],
+    response_shape={"messages": "list", "next_page_token": "str"},
+    error_codes={200: "ok", 400: "bad_request", 429: "rate_limit"},
+)
+
+_SEND_MESSAGE_BASE = EndpointSchema(
+    name="send_message",
+    params={"to": "str", "subject": "str", "body": "str"},
+    required=["to", "subject", "body"],
+    response_shape={"message_id": "str", "sent_at": "str"},
+    error_codes={200: "ok", 400: "bad_request", 422: "validation"},
+)
+
+_GET_MESSAGE_BASE = EndpointSchema(
+    name="get_message",
+    params={"message_id": "str"},
+    required=["message_id"],
+    response_shape={"id": "str", "from": "str", "subject": "str", "body": "str"},
+    error_codes={200: "ok", 404: "not_found"},
+)
+
+
+class MailAPI(BaseTool):
+    name = "mail"
+    baseline_schemas = {
+        "list_messages": _LIST_MESSAGES_BASE,
+        "send_message": _SEND_MESSAGE_BASE,
+        "get_message": _GET_MESSAGE_BASE,
+    }
+
+    def __init__(self, seed_data: dict) -> None:
+        super().__init__()
+        self.mailbox: list[dict] = list(seed_data.get("messages", []))
+        self.sent_messages: list[dict] = []
+        self.handlers = {
+            "list_messages": self._list_messages,
+            "send_message": self._send_message,
+            "get_message": self._get_message,
+        }
+
+    def _list_messages(self, params: dict) -> ToolResponse:
+        folder = params["folder"]
+        items = [m for m in self.mailbox if m.get("folder") == folder]
+        shape_keys = set(self.active_schemas["list_messages"].response_shape.keys())
+        if "items" in shape_keys and "next_cursor" in shape_keys:
+            return ToolResponse(
+                ok=True,
+                status=200,
+                body={
+                    "items": items[:10],
+                    "next_cursor": "cur_abc123" if len(items) > 10 else None,
+                },
+            )
+        return ToolResponse(
+            ok=True,
+            status=200,
+            body={
+                "messages": items[:10],
+                "next_page_token": "tok_xyz" if len(items) > 10 else None,
+            },
+        )
+
+    def _send_message(self, params: dict) -> ToolResponse:
+        mid = f"msg_{len(self.sent_messages) + len(self.mailbox) + 1}"
+        self.sent_messages.append({"id": mid, **params})
+        return ToolResponse(
+            ok=True,
+            status=200,
+            body={"message_id": mid, "sent_at": "2026-04-25T10:00:00Z"},
+        )
+
+    def _get_message(self, params: dict) -> ToolResponse:
+        mid = params["message_id"]
+        for m in self.mailbox:
+            if m.get("id") == mid:
+                return ToolResponse(ok=True, status=200, body=dict(m))
+        for m in self.sent_messages:
+            if m.get("id") == mid:
+                return ToolResponse(ok=True, status=200, body=dict(m))
+        return ToolResponse(ok=False, status=404, error="message not found")
+
+    def apply_drift(self, event: DriftEvent) -> None:
+        if event.kind == "field_rename" and event.endpoint == "list_messages":
+            self.active_schemas["list_messages"].response_shape = {
+                "items": "list",
+                "next_cursor": "str",
+            }
+            return
+
+        if event.kind == "endpoint_deprecation" and event.endpoint == "send_message":
+            self.active_schemas.pop("send_message", None)
+            self.handlers.pop("send_message", None)
+            new_schema = copy.deepcopy(self.baseline_schemas["send_message"])
+            new_schema.name = "messages.send"
+            self.active_schemas["messages.send"] = new_schema
+            self.handlers["messages.send"] = self._send_message
+            return
+
+        if event.kind == "new_required_param" and event.endpoint == "send_message":
+            schema = self.active_schemas["send_message"]
+            if "idempotency_key" not in schema.required:
+                schema.required.append("idempotency_key")
+            schema.params["idempotency_key"] = "str"
+            return
+
+        raise ValueError(
+            f"MailAPI.apply_drift: unhandled drift "
+            f"kind={event.kind!r} endpoint={event.endpoint!r}"
+        )