caura-bus-core 0.3.0__py3-none-any.whl

caura_bus_core/__init__.py

@@ -0,0 +1,46 @@
+"""Caura Bus: all messaging crosses the authenticated Caura platform API."""
+
+from .agent import AgentConfig, AgentInfo
+from .bus import IDEMPOTENCY_KEY_REUSED, RESYNC_EVENT, Bus, DirectoryIncomplete, PlatformError
+from .config import CONFIG_ENV_VAR, load_config, require_api_key
+from .consult import (
+    Answer,
+    Collection,
+    ConsultationBudget,
+    ConsultationCycleError,
+    ConsultationLimitError,
+    PresentedResponses,
+    ResponseCollector,
+    collect_responses,
+)
+from .envelope import Envelope, Kind, new_msg_id, new_thread_id, now_ms
+from .protocol import Claim, Receipt, SendMessage
+
+__all__ = [
+    "CONFIG_ENV_VAR",
+    "IDEMPOTENCY_KEY_REUSED",
+    "RESYNC_EVENT",
+    "AgentConfig",
+    "AgentInfo",
+    "Answer",
+    "Bus",
+    "DirectoryIncomplete",
+    "Claim",
+    "Collection",
+    "ConsultationBudget",
+    "ConsultationCycleError",
+    "ConsultationLimitError",
+    "Envelope",
+    "Kind",
+    "PlatformError",
+    "PresentedResponses",
+    "Receipt",
+    "ResponseCollector",
+    "SendMessage",
+    "collect_responses",
+    "load_config",
+    "new_msg_id",
+    "new_thread_id",
+    "now_ms",
+    "require_api_key",
+]

caura_bus_core/agent.py

@@ -0,0 +1,58 @@
+"""Agent identity and per-agent local config schemas."""
+
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class AgentInfo(BaseModel):
+    """Expected identity; the platform credential is authoritative."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    agent_id: str
+    tenant_id: str
+    fleet_id: str | None = None
+    description: str = ""
+    # Skills advertised with presence (e.g. by caura-bus-mcp); they grant no permissions.
+    capabilities: list[str] = Field(default_factory=list, max_length=50)
+
+
+class ConsultationLimits(BaseModel):
+    """Client-side bounds on peer consultation within one task (see SPEC "Consultation bounds")."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_requests: int = Field(default=4, ge=1, le=50)
+    deadline_seconds: float = Field(default=300, gt=0, le=3600)
+
+
+class AgentConfig(BaseModel):
+    """API location and expected identity. Keys are supplied through the environment."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    agent: AgentInfo
+    peers: list[str] = Field(default_factory=list)
+    api_url: str
+    allow_insecure_http: bool = False
+    consultation: ConsultationLimits = Field(default_factory=ConsultationLimits)
+
+    @field_validator("api_url")
+    @classmethod
+    def valid_url(cls, value: str) -> str:
+        url = urlsplit(value)
+        if (
+            url.scheme not in {"https", "http"}
+            or not url.hostname
+            or url.username
+            or url.password
+            or url.query
+            or url.fragment
+        ):
+            raise ValueError("api_url must be a Caura HTTP(S) origin without credentials, query or fragment")
+        if url.path not in {"", "/"}:
+            raise ValueError("api_url must be the gateway origin, without /api/v1")
+        return value.rstrip("/")

caura_bus_core/bus.py

@@ -0,0 +1,452 @@
+"""Async client. No Redis access, anonymous mode, or fallback transport."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import secrets
+from time import monotonic
+
+import httpx
+
+from .agent import AgentConfig
+from .collaboration import AgentDescription, Checkpoint, Presence
+from .config import require_api_key
+from .protocol import Claim, Receipt, SendMessage
+from .retry import Backoff, retry_after_seconds, transient_status
+
+# Sent instead of a gap when retention removed history after the stream cursor.
+RESYNC_EVENT = "stream.resync_required"
+
+
+class HumanRequired(RuntimeError):
+    def __init__(self, intervention):
+        self.intervention = intervention
+        super().__init__("Caura requires human input before this work can continue")
+
+
+# Reusing an Idempotency-Key with a different message (HTTP 409). Recover by
+# sending the new message under a new key; resend under the same key only to
+# retry the identical message.
+IDEMPOTENCY_KEY_REUSED = "COLLABORATION_IDEMPOTENCY_KEY_REUSED"
+
+
+class PlatformError(RuntimeError):
+    def __init__(self, status: int, detail: object):
+        self.status = status
+        self.detail = detail
+        # Stable machine-readable code when Caura supplies one (e.g. IDEMPOTENCY_KEY_REUSED).
+        code = detail.get("code") if isinstance(detail, dict) else None
+        self.code: str | None = code if isinstance(code, str) else None
+        message = detail.get("message") if isinstance(detail, dict) else None
+        text = f"{self.code}: {message}" if self.code and isinstance(message, str) else detail
+        super().__init__(f"Caura returned {status}: {text}")
+
+
+# Directory pagination bounds. The server pages ``agents``/``discover`` with an
+# opaque keyset cursor and accepts 1-500 agents per page.
+DIRECTORY_PAGE_MAX = 500
+DIRECTORY_PAGE_DEFAULT = 100
+DIRECTORY_MAX_PAGES = 200
+
+
+class DirectoryIncomplete(RuntimeError):
+    """The directory has more pages than a full listing is allowed to fetch."""
+
+
+def _page_size(limit: int) -> int:
+    if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= DIRECTORY_PAGE_MAX:
+        raise ValueError(f"limit must be between 1 and {DIRECTORY_PAGE_MAX}")
+    return limit
+
+
+def _directory_page(result) -> dict:
+    # A server without directory pagination ignores cursor/limit and returns
+    # its capped bare list; it offers no continuation, so treat it as final.
+    if isinstance(result, list):
+        return {"agents": result, "next_cursor": None}
+    return {"agents": result["agents"], "next_cursor": result.get("next_cursor")}
+
+
+class Bus:
+    def __init__(
+        self,
+        config: AgentConfig,
+        *,
+        api_key: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        if config.api_url.startswith("http:") and not config.allow_insecure_http:
+            raise ValueError("HTTPS is required; allow_insecure_http is only for isolated local demos")
+        self.config = config
+        self._notice_session: str | None = None
+        self._notice_receipt: str | None = None
+        self._http = httpx.AsyncClient(
+            base_url=config.api_url + "/api/v1/bus/",
+            headers={"X-API-Key": api_key or require_api_key()},
+            timeout=httpx.Timeout(20, connect=5),
+            follow_redirects=False,
+            transport=transport,
+            trust_env=False,
+        )
+
+    async def __aenter__(self):
+        try:
+            await self.connect()
+        except BaseException:
+            await self.close()
+            raise
+        return self
+
+    async def __aexit__(self, *_):
+        await self.close()
+
+    async def connect(self):
+        identity = await self.request("GET", "identity")
+        expected = self.config.agent
+        if (identity["agent_id"], identity["tenant_id"]) != (expected.agent_id, expected.tenant_id):
+            raise PlatformError(403, "credential does not match configured agent and tenant")
+        return identity
+
+    async def close(self):
+        await self._http.aclose()
+
+    async def request(self, method: str, path: str, *, retry_safe: bool = False, **kwargs):
+        # Snapshot proof of the previous response; retries retain exactly the
+        # same acknowledgement even if another concurrent call receives notices.
+        headers = dict(kwargs.pop("headers", {}))
+        if self._notice_session and self._notice_receipt:
+            headers["X-Caura-Session-ID"] = self._notice_session
+            headers["X-Caura-Notice-Receipt"] = self._notice_receipt
+        kwargs["headers"] = headers
+        # Only operations with durable idempotency retry ambiguous responses.
+        for attempt in range(3):
+            hinted = None
+            try:
+                response = await self._http.request(method, path, **kwargs)
+            except httpx.TransportError:
+                if not retry_safe or attempt == 2:
+                    raise
+            else:
+                if response.is_success:
+                    return response.json()
+                if not transient_status(response.status_code) or not retry_safe or attempt == 2:
+                    try:
+                        detail = response.json().get("detail", "request rejected")
+                    except ValueError:
+                        detail = "gateway rejected request"
+                    raise PlatformError(response.status_code, detail)
+                # A shed or overloaded service says when to come back; honour it
+                # (capped) instead of returning on the fixed backoff alone.
+                hinted = retry_after_seconds(response)
+            delay = 0.25 * (2**attempt)
+            if hinted is not None:
+                delay = max(delay, hinted)
+            await asyncio.sleep(delay + secrets.randbelow(100) / 1000)
+        raise AssertionError("unreachable")
+
+    async def send(self, message: SendMessage, *, idempotency_key: str) -> Receipt:
+        if (
+            message.kind != "response"
+            and "*" not in self.config.peers
+            and not set(message.to) <= set(self.config.peers)
+        ):
+            raise ValueError("recipient is outside the local peer allow-list")
+        if not idempotency_key or len(idempotency_key) > 128:
+            raise ValueError("idempotency_key must contain 1–128 characters")
+        result = await self.request(
+            "POST",
+            "messages",
+            json=message.model_dump(),
+            headers={"Idempotency-Key": idempotency_key},
+            retry_safe=True,
+        )
+        return Receipt.model_validate(result)
+
+    async def claim(self, lease_seconds: int = 30) -> Claim | None:
+        data = await self.request("POST", "inbox/claim", json={"lease_seconds": lease_seconds})
+        return Claim.model_validate(data["delivery"]) if data["delivery"] else None
+
+    async def wait(self, session_id: str, timeout: float = 50) -> Claim | None:
+        result = await self.wait_result(session_id, timeout)
+        return Claim.model_validate(result["delivery"]) if result["delivery"] else None
+
+    async def wait_result(self, session_id: str, timeout: float = 50) -> dict:
+        # Short HTTP polls fit the Caura gateway's 25-second upstream timeout and
+        # revalidate credentials; the model still sees one bounded MCP wait.
+        deadline = monotonic() + timeout
+        failures = 0
+        responded = False
+        while True:
+            remaining = max(0, deadline - monotonic())
+            poll = min(20, remaining)
+            try:
+                async with asyncio.timeout(remaining + 1 if timeout else 5):
+                    data = await self.request(
+                        "POST",
+                        "inbox/wait",
+                        json={"session_id": session_id, "timeout": poll},
+                        timeout=httpx.Timeout(min(poll + 5, remaining + 1) if timeout else 5, connect=5),
+                    )
+                responded = True
+                failures = 0
+                if data.get("notice_receipt"):
+                    self._notice_session = session_id
+                    self._notice_receipt = data["notice_receipt"]
+                if data["delivery"] or data.get("notices"):
+                    return data
+            except PlatformError as exc:
+                if exc.status < 500:
+                    raise
+                failures += 1
+            except (httpx.TransportError, TimeoutError):
+                failures += 1
+            remaining = deadline - monotonic()
+            if remaining <= 0 or not timeout:
+                if responded:
+                    return {"delivery": None, "notices": []}
+                raise PlatformError(503, "Caura remained unavailable during wait; retry wait")
+            if failures:
+                await asyncio.sleep(min(remaining, 0.25 * 2 ** min(failures - 1, 4)))
+
+    async def inbox_state(self):
+        return await self.request("GET", "inbox/state")
+
+    async def delivery_action(self, delivery_id: str, action: str, token=None, **params):
+        return await self.request(
+            "POST",
+            f"deliveries/{delivery_id}/{action}",
+            json={"lease_token": token, **params},
+            retry_safe=action in {"ack", "progress"},
+        )
+
+    async def reply(
+        self,
+        delivery_id: str,
+        *,
+        token=None,
+        idempotency_key: str,
+        body: str,
+        reply_to=None,
+        ack=True,
+    ):
+        return await self.request(
+            "POST",
+            f"deliveries/{delivery_id}/reply",
+            json={"lease_token": token, "body": body, "reply_to": reply_to, "ack": ack},
+            headers={"Idempotency-Key": idempotency_key},
+            retry_safe=True,
+        )
+
+    async def settle(self, claim: Claim, action: str):
+        if action not in {"ack", "nack", "renew", "paused"}:
+            raise ValueError("unknown delivery action")
+        return await self.request(
+            "POST",
+            f"deliveries/{claim.delivery_id}/{action}",
+            json={"lease_token": claim.lease_token},
+            retry_safe=action == "ack",
+        )
+
+    async def agents(self, fleet_id: str | None = None):
+        """First directory page only, as a bare list (legacy). Prefer ``agents_page``/``agents_all``."""
+        return await self.request("GET", "agents", params={"fleet_id": fleet_id} if fleet_id else {})
+
+    async def agents_page(
+        self, fleet_id: str | None = None, *, cursor: str | None = None, limit: int = DIRECTORY_PAGE_DEFAULT
+    ) -> dict:
+        """One bounded directory page: ``{"agents", "next_cursor"}``; more exist while ``next_cursor`` is set."""
+        params = {"fleet_id": fleet_id, "cursor": cursor, "limit": _page_size(limit)}
+        return _directory_page(
+            await self.request("GET", "agents", params={k: v for k, v in params.items() if v is not None})
+        )
+
+    async def agents_all(self, fleet_id: str | None = None, *, max_pages: int = DIRECTORY_MAX_PAGES) -> list:
+        """Every registered agent, following ``next_cursor`` to the last page."""
+        return await self._all_pages(
+            lambda cursor: self.agents_page(fleet_id, cursor=cursor, limit=DIRECTORY_PAGE_MAX), max_pages
+        )
+
+    async def _all_pages(self, fetch, max_pages: int) -> list:
+        agents: list = []
+        cursor = None
+        for _ in range(max_pages):
+            page = await fetch(cursor)
+            agents.extend(page["agents"])
+            cursor = page["next_cursor"]
+            if cursor is None:
+                return agents
+        raise DirectoryIncomplete(f"agent directory exceeds {max_pages} pages")
+
+    async def recent(
+        self,
+        *,
+        thread_id: str | None = None,
+        peer_agent_id: str | None = None,
+        limit: int = 20,
+        before: str | None = None,
+        reply_to: str | None = None,
+    ):
+        params = {
+            "limit": limit,
+            "thread_id": thread_id,
+            "peer_agent_id": peer_agent_id,
+            "before": before,
+            "reply_to": reply_to,
+        }
+        return await self.request(
+            "GET", "messages", params={k: v for k, v in params.items() if v is not None}
+        )
+
+    async def threads(self):
+        return await self.request("GET", "threads")
+
+    async def requests(self, *, state=None, limit=20):
+        return await self.request(
+            "GET",
+            "requests",
+            params={k: v for k, v in {"state": state, "limit": limit}.items() if v is not None},
+        )
+
+    async def status(self, message_id: str):
+        return await self.request("GET", f"messages/{message_id}")
+
+    async def memory_context(self, *, message_id: str | None = None, delivery_id: str | None = None):
+        from .protocol import MemoryContextRequest
+
+        params = MemoryContextRequest(message_id=message_id, delivery_id=delivery_id)
+        return await self.request("GET", "memory-context", params=params.model_dump(exclude_none=True))
+
+    async def advertise(self, profile: Presence):
+        # Unset optional fields (host, runtime) stay off the wire: servers that
+        # predate them reject unknown keys.
+        return await self.request(
+            "PUT", "presence", json=profile.model_dump(exclude_none=True), retry_safe=True
+        )
+
+    async def description(self):
+        """This agent's registered description (``description`` may be null)."""
+        return await self.request("GET", "agents/me/description", retry_safe=True)
+
+    async def describe(self, description: str | None):
+        """Set (or, with null/blank, clear) this agent's registered description."""
+        body = AgentDescription(description=description)
+        return await self.request("PUT", "agents/me/description", json=body.model_dump(), retry_safe=True)
+
+    async def discover(self, *, capability: str | None = None, available_only=True, fleet_id=None):
+        """First discovery page only, as a bare list (legacy). Prefer ``discover_page``."""
+        params = {"capability": capability, "available_only": available_only, "fleet_id": fleet_id}
+        return await self.request(
+            "GET", "discover", params={k: v for k, v in params.items() if v is not None}
+        )
+
+    async def discover_page(
+        self,
+        *,
+        capability: str | None = None,
+        available_only=True,
+        fleet_id=None,
+        cursor: str | None = None,
+        limit: int = DIRECTORY_PAGE_DEFAULT,
+    ) -> dict:
+        """One bounded discovery page: ``{"agents", "next_cursor"}``.
+
+        Pass ``next_cursor`` back with the same filters for the next page; a
+        cursor is bound to its filters and tenant.
+        """
+        params = {
+            "capability": capability,
+            "available_only": available_only,
+            "fleet_id": fleet_id,
+            "cursor": cursor,
+            "limit": _page_size(limit),
+        }
+        return _directory_page(
+            await self.request("GET", "discover", params={k: v for k, v in params.items() if v is not None})
+        )
+
+    async def discover_all(
+        self,
+        *,
+        capability: str | None = None,
+        available_only=True,
+        fleet_id=None,
+        max_pages: int = DIRECTORY_MAX_PAGES,
+    ) -> list:
+        """Every matching agent, following ``next_cursor`` to the last page."""
+        return await self._all_pages(
+            lambda cursor: self.discover_page(
+                capability=capability,
+                available_only=available_only,
+                fleet_id=fleet_id,
+                cursor=cursor,
+                limit=DIRECTORY_PAGE_MAX,
+            ),
+            max_pages,
+        )
+
+    async def checkpoint(self, checkpoint: Checkpoint):
+        result = await self.request("POST", "checkpoints", json=checkpoint.model_dump(), retry_safe=True)
+        if result["decision"] == "human_required":
+            raise HumanRequired(result["intervention"])
+        return result
+
+    async def escalate(self, delivery_id: str, reason: str):
+        return await self.request(
+            "POST", "interventions", json={"delivery_id": delivery_id, "reason": reason}
+        )
+
+    async def resync(self):
+        """Reload durable inbox state over REST after the stream lost history.
+
+        A read, so transient failures are retried like other safe calls.
+        """
+        return await self.request("GET", "inbox/state", retry_safe=True)
+
+    async def events(self, after=0):
+        """Resume a live stream by durable cursor; reconnect revalidates credentials.
+
+        When retention removed events after the cursor, Caura sends
+        ``stream.resync_required`` instead of skipping them. That event is
+        yielded with ``state`` holding a fresh REST snapshot (``resync()``),
+        and the stream continues from the event's ``resume_after``. Consumers
+        must treat it as "anything may have changed", never as unknown noise.
+        """
+        cursor = after
+        backoff = Backoff(maximum=15)
+        while True:
+            try:
+                async with self._http.stream(
+                    "GET",
+                    "events",
+                    params={"after": cursor},
+                    headers={"Accept": "text/event-stream"},
+                ) as response:
+                    if response.status_code != 200:
+                        if not transient_status(response.status_code):
+                            raise PlatformError(response.status_code, "live event access failed")
+                    else:
+                        async for line in response.aiter_lines():
+                            if line.startswith("data: "):
+                                event = json.loads(line[6:])
+                                if event.get("event_type") == RESYNC_EVENT:
+                                    # Advance only after the reload succeeds;
+                                    # a failed reload reconnects and resyncs again.
+                                    try:
+                                        state = await self.resync()
+                                    except PlatformError as exc:
+                                        if not transient_status(exc.status):
+                                            raise
+                                        break
+                                    event = {**event, "state": state}
+                                    payload = event.get("payload") or {}
+                                    cursor = int(payload.get("resume_after", event["seq"]))
+                                else:
+                                    cursor = event["seq"]
+                                backoff.reset()
+                                yield event
+            except httpx.TransportError:
+                pass
+            # This also bounds reconnects when an upstream closes an empty
+            # stream successfully, without supplying an event or heartbeat.
+            await backoff.sleep()

caura_bus_core/collaboration.py

@@ -0,0 +1,103 @@
+"""Agent discovery, runtime checkpoints and human intervention contracts."""
+
+from typing import Literal
+
+from pydantic import Field, field_validator
+
+from .protocol import StrictModel
+
+AGENT_DESCRIPTION_MAX_LENGTH = 1000
+PRESENCE_HOST_MAX_LENGTH = 255
+PRESENCE_RUNTIME_MAX_LENGTH = 64
+
+
+class AgentDescription(StrictModel):
+    """Registered, durable expertise text shown in the agent directory.
+
+    Unlike ``Presence.description`` (runtime, expires with the session), this
+    survives while the agent is offline. ``null`` or blank clears it.
+    """
+
+    description: str | None = Field(max_length=AGENT_DESCRIPTION_MAX_LENGTH)
+
+    @field_validator("description")
+    @classmethod
+    def normalized(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        if any(ord(c) < 32 and c not in "\n\t" for c in value):
+            raise ValueError("description must not contain control characters")
+        return value.strip() or None
+
+
+class Presence(StrictModel):
+    session_id: str = Field(min_length=1, max_length=128)
+    display_name: str = Field(min_length=1, max_length=120)
+    description: str = Field(default="", max_length=2000)
+    capabilities: list[str] = Field(default_factory=list, max_length=50)
+    # ``waiting_for_user``: the session is held at a prompt only its person can
+    # answer (a permission request), so it neither works nor takes new work.
+    status: Literal["ready", "busy", "waiting_for_user", "offline"] = "ready"
+    supports_interrupt: bool = False
+    # Where the session runs, for people reading the directory: the machine's
+    # hostname and the agent runtime (``claude-code``, ``codex``, ...). Optional
+    # and omitted from the wire when unset, so older servers keep accepting it.
+    host: str | None = Field(default=None, max_length=PRESENCE_HOST_MAX_LENGTH)
+    runtime: str | None = Field(default=None, max_length=PRESENCE_RUNTIME_MAX_LENGTH)
+
+    @field_validator("capabilities")
+    @classmethod
+    def bounded_capabilities(cls, values):
+        if any(not v.strip() or len(v) > 80 for v in values):
+            raise ValueError("capabilities must contain 1–80 characters")
+        return sorted(set(values))
+
+    @field_validator("host", "runtime")
+    @classmethod
+    def single_line(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        if any(ord(c) < 32 or ord(c) == 127 for c in value):
+            raise ValueError("host and runtime must be a single line of text")
+        return value.strip() or None
+
+
+class Checkpoint(StrictModel):
+    delivery_id: str = Field(min_length=1, max_length=80)
+    lease_token: str = Field(min_length=1, max_length=128)
+    checkpoint_key: str = Field(min_length=1, max_length=128)
+    summary: str = Field(min_length=1, max_length=2000)
+    proposed_action: str = Field(min_length=1, max_length=4000)
+    action_type: Literal["read", "write", "external", "destructive"] = "read"
+    confidence: float = Field(default=1, ge=0, le=1)
+    missing_information: list[str] = Field(default_factory=list, max_length=20)
+    conflicting_results: bool = False
+    request_human: bool = False
+
+
+class HumanDecision(StrictModel):
+    version: int = Field(ge=1)
+    action: Literal["approve", "reject", "redirect", "nudge", "reassign", "cancel"]
+    target_agent_id: str | None = Field(default=None, min_length=1, max_length=256)
+    instructions: str = Field(default="", max_length=4000)
+    allow_unconfirmed: bool = False
+
+
+class Interrupt(StrictModel):
+    delivery_id: str = Field(min_length=1, max_length=80)
+    reason: str = Field(min_length=1, max_length=2000)
+
+
+class CollaborationPolicy(StrictModel):
+    request_reply_timeout_seconds: int = Field(default=900, ge=60, le=604800)
+    unanswered_after_seconds: int = Field(default=86400, ge=60, le=604800)
+    overdue_action: Literal["notify_sender", "nudge", "escalate"] = "notify_sender"
+    messaging_scope: Literal["same_fleet", "tenant"] = "same_fleet"
+    processing_timeout_seconds: int = Field(default=600, ge=30, le=86400)
+    max_extensions: int = Field(default=6, ge=0, le=100)
+    minimum_confidence: float = Field(default=0.75, ge=0, le=1)
+    require_human_for: list[Literal["read", "write", "external", "destructive"]] = Field(
+        default_factory=lambda: ["external", "destructive"]
+    )
+    escalate_missing_information: bool = True
+    escalate_conflicts: bool = True

caura_bus_core/config.py

@@ -0,0 +1,22 @@
+"""Strict configuration; obsolete direct-transport settings fail at startup."""
+
+import os
+import tomllib
+from pathlib import Path
+
+from .agent import AgentConfig
+
+CONFIG_ENV_VAR = "CAURA_BUS_AGENT_CONFIG"
+DEFAULT_CONFIG_PATH = Path("caura-bus.toml")
+
+
+def load_config(path: Path | None = None) -> AgentConfig:
+    path = path or Path(os.environ.get(CONFIG_ENV_VAR, str(DEFAULT_CONFIG_PATH)))
+    return AgentConfig.model_validate(tomllib.loads(path.read_text()))
+
+
+def require_api_key() -> str:
+    key = os.environ.get("CAURA_API_KEY", "").strip()
+    if not key:
+        raise RuntimeError("CAURA_API_KEY is required: use a Caura agent-scoped credential")
+    return key