agentdraft 0.1.0__tar.gz → 0.1.2__tar.gz

agentdraft-0.1.2/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: agentdraft
+Version: 0.1.2
+Summary: AgentDraft SDK — ops API for AI agents with inbox, conflict-free calendar booking, and audit trail.
+Author-email: AgentDraft Labs <hello@agentdraft.io>
+License: MIT
+Project-URL: Homepage, https://agentdraft.io
+Project-URL: Documentation, https://agentdraft.io/docs
+Project-URL: Specification, https://agentdraft.io/spec
+Project-URL: Changelog, https://agentdraft.io/changelog
+Project-URL: Repository, https://github.com/ryabinski-labs/agentdraft
+Project-URL: Issues, https://github.com/ryabinski-labs/agentdraft/issues
+Keywords: agentdraft,ai-agents,agents,calendar,scheduling,booking,coordination,langchain,crewai,autogen,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Dynamic: license-file
+
+# agentdraft — Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/agentdraft.svg)](https://pypi.org/project/agentdraft/)
+[![Python](https://img.shields.io/pypi/pyversions/agentdraft.svg)](https://pypi.org/project/agentdraft/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://agentdraft.io/legal/license)
+
+**AgentDraft is the coordination layer for AI scheduling agents.** When two
+or more agents — your sales bot, a Cal.com handler, an internal recruiter,
+a Claude/OpenAI assistant — write to the same calendar, AgentDraft is the
+one API that decides who wins, atomically, with a tamper-evident audit row
+for every commit.
+
+This is the official Python SDK. It gives an agent a typed, one-line
+surface to participate.
+
+- **Protocol spec:** <https://agentdraft.io/spec>
+- **Why it exists:** <https://agentdraft.io/why>
+- **Live API reference:** <https://agentdraft.io/docs>
+
+## Install
+
+```bash
+pip install agentdraft
+```
+
+Requires Python 3.9+.
+
+## Upgrade
+
+```bash
+pip install -U agentdraft
+```
+
+Release notes: <https://agentdraft.io/changelog>
+
+## Quickstart
+
+```python
+from datetime import datetime, timedelta, timezone
+from agentdraft import Client, Conflict
+
+client = Client(api_key="avs_live_...")   # or set AGENTDRAFT_API_KEY
+
+start = datetime.now(timezone.utc) + timedelta(hours=4)
+end   = start + timedelta(minutes=30)
+
+try:
+    booking = client.bookings.commit(
+        start=start, end=end,
+        idempotency_key="ik_call_42",
+        title="Discovery call",
+        invitee={"name": "Ada Lovelace", "email": "ada@example.com"},
+    )
+    print("booked:", booking.booking_id)
+except Conflict as e:
+    print(f"outranked by {e.winning_agent_id} (rank {e.winning_agent_priority})")
+```
+
+`title` and `invitee` (`{name, email, notes}`, all optional) are first-class
+fields: they're persisted on the booking, echoed back on the returned
+`Booking`, and shown to the calendar owner in the dashboard. A top-level
+`title` supersedes the legacy `metadata={"title": ...}`. `client.agents.me()`
+also returns the owner's `timezone` so a client can render slots in their
+zone.
+
+A losing agent gets a typed `Conflict` exception, not a timeout — it
+knows who won, by what priority, and where the audit row lives, so
+fallback behavior (propose an alternate, escalate, defer) is a clean
+`except` clause away.
+
+## Why a separate API?
+
+Coordinator frameworks (LangChain, LangGraph, CrewAI, AutoGen, Composio,
+the OpenAI Agents SDK) coordinate *work between agents* — sequential,
+parallel, or graph orchestration of LLM calls and tools. None of them
+solve **write contention on the calendar itself**: two agents firing
+`POST /events` against Google Calendar at the same moment will both
+succeed, and you have a double-booking.
+
+AgentDraft solves only that problem, and solves it once. Every agent
+the calendar owner runs calls `bookings.commit(...)` against AgentDraft
+before touching the real calendar. The conflict engine uses
+time-bucketed conditional writes in DynamoDB inside a single
+`TransactWriteItems` — atomic, race-free, no locks. The user ranks
+their agents in the dashboard; ties go to the higher-rank agent;
+recent commits can be evicted by higher-priority agents inside a
+configurable bump window.
+
+## See the race
+
+The repo ships a multi-agent race demo. With the local stack up:
+
+```bash
+git clone https://github.com/ryabinski-labs/agentdraft && cd agentdraft
+docker compose up -d dynamodb
+pip install -e ".[dev]" -e sdks/python
+uvicorn app.main:app --port 8080 &
+python scripts/demo_race.py            # 5 agents, ranked priorities, one slot
+```
+
+Five agents fire concurrently at the same target slot. The highest-rank
+agent wins; the rest get `409 outranked` with the winner's identity for
+graceful fallback. The demo prints per-agent latency, the winning
+booking id, and a link to the audit trail of the whole race.
+
+## Authentication
+
+API keys are issued from the AgentDraft dashboard and start with
+`avs_live_`. Pass it explicitly or let the client read it from the
+environment:
+
+```python
+Client(api_key="avs_live_...")
+# or
+import os; os.environ["AGENTDRAFT_API_KEY"] = "avs_live_..."
+Client()
+```
+
+For local development against a dev backend, point at it via
+`AGENTDRAFT_BASE_URL` or the `base_url=` kwarg.
+
+## Surface
+
+| Attribute | Purpose |
+|---|---|
+| `client.availability` | Read merged availability across all agents writing to the calendar |
+| `client.bookings`     | `hold`, `release`, `commit`, `cancel` — the four state transitions |
+| `client.agents`       | `me()` — confirm key + current priority + scopes |
+| `client.mailbox`      | Inbound/outbound mail surface for agents that book via email |
+
+All blocking I/O. An async client is on the roadmap; for now wrap with
+`asyncio.to_thread` if you need concurrency.
+
+## Error types
+
+Every failure is a typed exception so callers can branch precisely:
+
+- `Conflict` — your write was outranked. Carries `winning_booking_id`,
+  `winning_agent_id`, `winning_agent_priority`, `your_priority`, and
+  `reason`. The winning booking's `audit_event_id` is available on the
+  returned `Booking` model for the agent that *did* win.
+- `AuthError` — bad / missing / expired API key.
+- `RateLimited` — token bucket exhausted. Has `retry_after` (seconds).
+- `RuleViolation` — request was syntactically valid but violated a
+  rule (focus block, daily cap, business hours).
+- `AgentDraftError` — base class; catch this if you only need a
+  catch-all.
+
+## Idempotency
+
+Pass `idempotency_key=` to `bookings.commit(...)`. The server caches the
+result by `(agent_id, key)` for 24 hours, so a retry over a flaky network
+returns the original booking, not a duplicate.
+
+## Use with LangChain / CrewAI / AutoGen
+
+The SDK is framework-agnostic — wrap any method in a `Tool` and pass it
+to your agent. A first-party `agentdraft-langchain` package with ready
+`BookingTool` / `AvailabilityTool` / `ConflictAwareBookingTool`
+wrappers is on the roadmap.
+
+## Links
+
+- Protocol spec: <https://agentdraft.io/spec>
+- API docs: <https://agentdraft.io/docs>
+- Changelog: <https://agentdraft.io/changelog>
+- Source & issues: <https://github.com/ryabinski-labs/agentdraft>
+- TypeScript SDK: [`agentdraft`](https://www.npmjs.com/package/agentdraft)
+
+## Security
+
+Found a vulnerability? See <https://agentdraft.io/security> — **do not**
+open a public issue for a security report.
+
+## License
+
+MIT — see <https://agentdraft.io/legal/license>.

agentdraft-0.1.2/README.md

@@ -0,0 +1,177 @@
+# agentdraft — Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/agentdraft.svg)](https://pypi.org/project/agentdraft/)
+[![Python](https://img.shields.io/pypi/pyversions/agentdraft.svg)](https://pypi.org/project/agentdraft/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://agentdraft.io/legal/license)
+
+**AgentDraft is the coordination layer for AI scheduling agents.** When two
+or more agents — your sales bot, a Cal.com handler, an internal recruiter,
+a Claude/OpenAI assistant — write to the same calendar, AgentDraft is the
+one API that decides who wins, atomically, with a tamper-evident audit row
+for every commit.
+
+This is the official Python SDK. It gives an agent a typed, one-line
+surface to participate.
+
+- **Protocol spec:** <https://agentdraft.io/spec>
+- **Why it exists:** <https://agentdraft.io/why>
+- **Live API reference:** <https://agentdraft.io/docs>
+
+## Install
+
+```bash
+pip install agentdraft
+```
+
+Requires Python 3.9+.
+
+## Upgrade
+
+```bash
+pip install -U agentdraft
+```
+
+Release notes: <https://agentdraft.io/changelog>
+
+## Quickstart
+
+```python
+from datetime import datetime, timedelta, timezone
+from agentdraft import Client, Conflict
+
+client = Client(api_key="avs_live_...")   # or set AGENTDRAFT_API_KEY
+
+start = datetime.now(timezone.utc) + timedelta(hours=4)
+end   = start + timedelta(minutes=30)
+
+try:
+    booking = client.bookings.commit(
+        start=start, end=end,
+        idempotency_key="ik_call_42",
+        title="Discovery call",
+        invitee={"name": "Ada Lovelace", "email": "ada@example.com"},
+    )
+    print("booked:", booking.booking_id)
+except Conflict as e:
+    print(f"outranked by {e.winning_agent_id} (rank {e.winning_agent_priority})")
+```
+
+`title` and `invitee` (`{name, email, notes}`, all optional) are first-class
+fields: they're persisted on the booking, echoed back on the returned
+`Booking`, and shown to the calendar owner in the dashboard. A top-level
+`title` supersedes the legacy `metadata={"title": ...}`. `client.agents.me()`
+also returns the owner's `timezone` so a client can render slots in their
+zone.
+
+A losing agent gets a typed `Conflict` exception, not a timeout — it
+knows who won, by what priority, and where the audit row lives, so
+fallback behavior (propose an alternate, escalate, defer) is a clean
+`except` clause away.
+
+## Why a separate API?
+
+Coordinator frameworks (LangChain, LangGraph, CrewAI, AutoGen, Composio,
+the OpenAI Agents SDK) coordinate *work between agents* — sequential,
+parallel, or graph orchestration of LLM calls and tools. None of them
+solve **write contention on the calendar itself**: two agents firing
+`POST /events` against Google Calendar at the same moment will both
+succeed, and you have a double-booking.
+
+AgentDraft solves only that problem, and solves it once. Every agent
+the calendar owner runs calls `bookings.commit(...)` against AgentDraft
+before touching the real calendar. The conflict engine uses
+time-bucketed conditional writes in DynamoDB inside a single
+`TransactWriteItems` — atomic, race-free, no locks. The user ranks
+their agents in the dashboard; ties go to the higher-rank agent;
+recent commits can be evicted by higher-priority agents inside a
+configurable bump window.
+
+## See the race
+
+The repo ships a multi-agent race demo. With the local stack up:
+
+```bash
+git clone https://github.com/ryabinski-labs/agentdraft && cd agentdraft
+docker compose up -d dynamodb
+pip install -e ".[dev]" -e sdks/python
+uvicorn app.main:app --port 8080 &
+python scripts/demo_race.py            # 5 agents, ranked priorities, one slot
+```
+
+Five agents fire concurrently at the same target slot. The highest-rank
+agent wins; the rest get `409 outranked` with the winner's identity for
+graceful fallback. The demo prints per-agent latency, the winning
+booking id, and a link to the audit trail of the whole race.
+
+## Authentication
+
+API keys are issued from the AgentDraft dashboard and start with
+`avs_live_`. Pass it explicitly or let the client read it from the
+environment:
+
+```python
+Client(api_key="avs_live_...")
+# or
+import os; os.environ["AGENTDRAFT_API_KEY"] = "avs_live_..."
+Client()
+```
+
+For local development against a dev backend, point at it via
+`AGENTDRAFT_BASE_URL` or the `base_url=` kwarg.
+
+## Surface
+
+| Attribute | Purpose |
+|---|---|
+| `client.availability` | Read merged availability across all agents writing to the calendar |
+| `client.bookings`     | `hold`, `release`, `commit`, `cancel` — the four state transitions |
+| `client.agents`       | `me()` — confirm key + current priority + scopes |
+| `client.mailbox`      | Inbound/outbound mail surface for agents that book via email |
+
+All blocking I/O. An async client is on the roadmap; for now wrap with
+`asyncio.to_thread` if you need concurrency.
+
+## Error types
+
+Every failure is a typed exception so callers can branch precisely:
+
+- `Conflict` — your write was outranked. Carries `winning_booking_id`,
+  `winning_agent_id`, `winning_agent_priority`, `your_priority`, and
+  `reason`. The winning booking's `audit_event_id` is available on the
+  returned `Booking` model for the agent that *did* win.
+- `AuthError` — bad / missing / expired API key.
+- `RateLimited` — token bucket exhausted. Has `retry_after` (seconds).
+- `RuleViolation` — request was syntactically valid but violated a
+  rule (focus block, daily cap, business hours).
+- `AgentDraftError` — base class; catch this if you only need a
+  catch-all.
+
+## Idempotency
+
+Pass `idempotency_key=` to `bookings.commit(...)`. The server caches the
+result by `(agent_id, key)` for 24 hours, so a retry over a flaky network
+returns the original booking, not a duplicate.
+
+## Use with LangChain / CrewAI / AutoGen
+
+The SDK is framework-agnostic — wrap any method in a `Tool` and pass it
+to your agent. A first-party `agentdraft-langchain` package with ready
+`BookingTool` / `AvailabilityTool` / `ConflictAwareBookingTool`
+wrappers is on the roadmap.
+
+## Links
+
+- Protocol spec: <https://agentdraft.io/spec>
+- API docs: <https://agentdraft.io/docs>
+- Changelog: <https://agentdraft.io/changelog>
+- Source & issues: <https://github.com/ryabinski-labs/agentdraft>
+- TypeScript SDK: [`agentdraft`](https://www.npmjs.com/package/agentdraft)
+
+## Security
+
+Found a vulnerability? See <https://agentdraft.io/security> — **do not**
+open a public issue for a security report.
+
+## License
+
+MIT — see <https://agentdraft.io/legal/license>.

{agentdraft-0.1.0 → agentdraft-0.1.2}/agentdraft/__init__.py

@@ -16,27 +16,38 @@ Quickstart::
         booking = client.bookings.commit(
             start=start, end=end,
             idempotency_key="ik_call_42",
-            metadata={"title": "Discovery call"},
+            title="Discovery call",
+            invitee={"name": "Ada Lovelace", "email": "ada@example.com"},
         )
         print("booked:", booking.booking_id)
     except Conflict as e:
         print(f"outranked by {e.winning_agent_id} (rank {e.winning_agent_priority})")
 """
 
+__version__ = "0.1.2"
+
 from .client import Client
-from .errors import AgentDraftError, AuthError, Conflict, RateLimited, RuleViolation
+from .errors import (
+    AgentDraftError,
+    ApprovalTimeout,
+    AuthError,
+    Conflict,
+    ConsentRequired,
+    RateLimited,
+    RuleViolation,
+)
 from .models import Booking, Hold, Slot
 
 __all__ = [
     "Client",
     "AgentDraftError",
+    "ApprovalTimeout",
     "AuthError",
     "Conflict",
+    "ConsentRequired",
     "RateLimited",
     "RuleViolation",
     "Booking",
     "Hold",
     "Slot",
 ]
-
-__version__ = "0.1.0"

{agentdraft-0.1.0 → agentdraft-0.1.2}/agentdraft/client.py

@@ -3,15 +3,26 @@
 from __future__ import annotations
 
 import os
+import time
 from datetime import datetime
 from typing import Any, Optional
 
 import httpx
 
-from .errors import AgentDraftError, AuthError, Conflict, RateLimited, RuleViolation
+from . import __version__
+from .errors import (
+    AgentDraftError,
+    ApprovalTimeout,
+    AuthError,
+    Conflict,
+    ConsentRequired,
+    RateLimited,
+    RuleViolation,
+)
 from .models import AgentIdentity, Booking, Slot
 
 DEFAULT_BASE_URL = "https://api.agentdraft.io"
+DEFAULT_USER_AGENT = f"agentdraft-python/{__version__}"
 
 
 class Client:
@@ -37,7 +48,7 @@ class Client:
         *,
         base_url: Optional[str] = None,
         timeout: float = 10.0,
-        user_agent: str = "agentdraft-python/0.1.0",
+        user_agent: str = DEFAULT_USER_AGENT,
     ):
         api_key = api_key or os.environ.get("AGENTDRAFT_API_KEY")
         if not api_key:
@@ -55,6 +66,7 @@ class Client:
         self.bookings = _Bookings(self)
         self.agents = _Agents(self)
         self.mailbox = _Mailbox(self)
+        self.approvals = _Approvals(self)
 
     def close(self) -> None:
         self._http.close()
@@ -90,6 +102,15 @@ class Client:
     def _raise_for(self, status: int, body: dict, headers: dict) -> None:
         if status == 401 or status == 403:
             raise AuthError(body.get("detail") or str(body), status=status, body=body)
+        if status == 409 and body.get("error") == "consent_required":
+            raise ConsentRequired(
+                "consent_required",
+                body=body,
+                consent_request_id=body.get("consent_request_id"),
+                action=body.get("action"),
+                hold_id=body.get("hold_id"),
+                expires_at=body.get("expires_at"),
+            )
         if status == 409:
             raise Conflict(
                 body.get("error", "outranked"),
@@ -160,6 +181,9 @@ class _Bookings(_Resource):
         buffer_after_min: int = 0,
         bump_window_seconds: Optional[int] = None,
         metadata: Optional[dict] = None,
+        with_conferencing: bool = False,
+        title: Optional[str] = None,
+        invitee: Optional[dict] = None,
     ) -> Booking:
         return self._post(
             start=start,
@@ -170,6 +194,9 @@ class _Bookings(_Resource):
             buffer_after_min=buffer_after_min,
             bump_window_seconds=bump_window_seconds,
             metadata=metadata,
+            with_conferencing=with_conferencing,
+            title=title,
+            invitee=invitee,
         )
 
     def hold(
@@ -181,6 +208,8 @@ class _Bookings(_Resource):
         buffer_before_min: int = 0,
         buffer_after_min: int = 0,
         metadata: Optional[dict] = None,
+        title: Optional[str] = None,
+        invitee: Optional[dict] = None,
     ) -> Booking:
         return self._post(
             start=start,
@@ -190,6 +219,8 @@ class _Bookings(_Resource):
             buffer_before_min=buffer_before_min,
             buffer_after_min=buffer_after_min,
             metadata=metadata,
+            title=title,
+            invitee=invitee,
         )
 
     def release(self, hold_id: str) -> None:
@@ -212,6 +243,12 @@ class _Bookings(_Resource):
             body["bump_window_seconds"] = kwargs["bump_window_seconds"]
         if kwargs.get("metadata"):
             body["metadata"] = kwargs["metadata"]
+        if kwargs.get("with_conferencing"):
+            body["with_conferencing"] = True
+        if kwargs.get("title"):
+            body["title"] = kwargs["title"]
+        if kwargs.get("invitee"):
+            body["invitee"] = kwargs["invitee"]
 
         headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
         _, j, _ = self._c._request("POST", "/v1/bookings", json=body, headers=headers)
@@ -310,3 +347,84 @@ class _Mailbox(_Resource):
             "GET", f"/v1/mailbox/suppressions/{quote(address, safe='@+.')}"
         )
         return j
+
+
+TERMINAL_APPROVAL_STATUSES = frozenset({"approved", "denied", "expired"})
+
+
+class _Approvals(_Resource):
+    """Human sign-off for anything your agent is about to do (#446).
+
+    The action need not be an AgentDraft one — gate a deploy, a refund, or an
+    outbound email on the same call. Requires the ``approvals:request`` scope.
+
+        approval = client.approvals.request(
+            action_type="deploy.production",
+            summary="Ship v2.3.0 to production",
+            evidence={"commit": "a1b2c3d", "migrations": 2},
+        )
+        result = client.approvals.wait(approval["approval_id"])
+        if result["status"] != "approved":
+            raise SystemExit(f"stood down: {result['status']}")
+    """
+
+    def request(
+        self,
+        action_type: str,
+        summary: str,
+        *,
+        evidence: Optional[dict] = None,
+        ttl_seconds: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict:
+        """Open a request and return immediately with ``{approval_id, status,
+        expires_at}``. Nothing blocks until you call :meth:`wait`."""
+        body: dict[str, Any] = {"action_type": action_type, "summary": summary}
+        if evidence is not None:
+            body["evidence"] = evidence
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        _, j, _ = self._c._request("POST", "/v1/approvals", json=body, headers=headers)
+        return j
+
+    def get(self, approval_id: str) -> dict:
+        """Current state of a request, including its resolution once decided."""
+        _, j, _ = self._c._request("GET", f"/v1/approvals/{approval_id}")
+        return j
+
+    def wait(
+        self,
+        approval_id: str,
+        *,
+        timeout: Optional[float] = None,
+        poll_interval: float = 5.0,
+    ) -> dict:
+        """Block until a human decides, then return the resolved approval.
+
+        Returns on any terminal status — ``approved``, ``denied``, or
+        ``expired`` — so check ``result["status"]`` rather than assuming a
+        return means yes.
+
+        ``timeout`` is a client-side ceiling in seconds. Left unset, the wait
+        follows the request's own ``expires_at``: once it lapses the server
+        sweeps it to ``expired`` and this returns that, so the default never
+        loops forever. :class:`ApprovalTimeout` therefore only fires when *you*
+        set a timeout shorter than the request's life — the request stays
+        pending and resolvable when it does.
+        """
+        started = time.monotonic()
+        deadline = started + timeout if timeout is not None else None
+        while True:
+            current = self.get(approval_id)
+            if current.get("status") in TERMINAL_APPROVAL_STATUSES:
+                return current
+
+            waited = time.monotonic() - started
+            if deadline is not None and time.monotonic() + poll_interval > deadline:
+                raise ApprovalTimeout(
+                    f"approval {approval_id} still pending after {waited:.0f}s",
+                    approval_id=approval_id,
+                    waited_seconds=waited,
+                )
+            time.sleep(poll_interval)

{agentdraft-0.1.0 → agentdraft-0.1.2}/agentdraft/errors.py

@@ -46,6 +46,49 @@ class Conflict(AgentDraftError):
         self.reason = reason
 
 
+class ConsentRequired(AgentDraftError):
+    """409 — a high-impact action is gated on a human approve/deny (#236).
+
+    The slot is parked as a HOLD until a person decides on the dashboard, so the
+    action is neither committed nor lost. ``consent_request_id`` identifies the
+    pending decision; ``hold_id`` is the parked hold; ``expires_at`` is when the
+    park (and the request) lapse if nobody acts. Distinct from ``Conflict``: you
+    did not lose to another agent — you're waiting on a human.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 409,
+        body: dict,
+        consent_request_id: Optional[str] = None,
+        action: Optional[str] = None,
+        hold_id: Optional[str] = None,
+        expires_at: Optional[str] = None,
+    ):
+        super().__init__(message, status=status, body=body)
+        self.consent_request_id = consent_request_id
+        self.action = action
+        self.hold_id = hold_id
+        self.expires_at = expires_at
+
+
+class ApprovalTimeout(AgentDraftError):
+    """``approvals.wait()`` gave up before a human decided (#446).
+
+    Client-side only — the request is still pending on the server and a human
+    can still resolve it, so treat this as "not yet", not "denied". Poll again
+    with :meth:`Client.approvals.get` or wait again; ``approval_id`` is carried
+    so you can.
+    """
+
+    def __init__(self, message: str, *, approval_id: str, waited_seconds: float):
+        super().__init__(message)
+        self.approval_id = approval_id
+        self.waited_seconds = waited_seconds
+
+
 class RuleViolation(AgentDraftError):
     """422 — the proposed booking violates a rule (working hours, focus block, etc.)."""