dispatch_agents 0.10.1__tar.gz → 0.12.2__tar.gz

{dispatch_agents-0.10.1 → dispatch_agents-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dispatch_agents
-Version: 0.10.1
+Version: 0.12.2
 Summary: Dispatch Agents SDK
 License-File: LICENSE
 License-File: LICENSE-3rdparty.csv

dispatch_agents-0.12.2/RELEASE_NOTES.md

@@ -0,0 +1 @@
+BREAKING CHANGE: Compatibility changes to remove LiteLLM from backend.

{dispatch_agents-0.10.1 → dispatch_agents-0.12.2}/dispatch_agents/config.py

@@ -5,6 +5,7 @@ shared between CLI and backend.
 """
 
 import os
+import re
 from enum import StrEnum
 from typing import Any
 
@@ -25,6 +26,13 @@ RESERVED_ENV_VARS: frozenset[str] = frozenset(
     }
 )
 
+# Domain validation pattern for egress allow list.
+# Accepts exact FQDNs (api.openai.com) and wildcard prefixes (*.github.com).
+# Rejects URLs with schemes/ports/paths, IP addresses, and bare wildcards.
+_DOMAIN_PATTERN = re.compile(
+    r"^(\*\.)?([a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$"
+)
+
 
 class VolumeMode(StrEnum):
     """Volume access mode for persistent storage.
@@ -322,6 +330,98 @@ class ResourceConfig(BaseModel):
     )
 
 
+class DomainSelector(BaseModel):
+    """A single domain selector -- exactly one of match_name or match_pattern.
+
+    match_name is an exact FQDN (e.g. api.openai.com).
+    match_pattern is a wildcard prefix (e.g. *.github.com).
+
+    Serialises with camelCase aliases (matchName / matchPattern) to match the
+    downstream Cilium FQDN selector API.
+    """
+
+    match_name: str | None = Field(
+        default=None,
+        description="Exact FQDN to allow. Must match the entire domain name exactly "
+        "(e.g. 'api.openai.com' matches only 'api.openai.com').",
+    )
+    match_pattern: str | None = Field(
+        default=None,
+        description="Wildcard pattern to allow. Uses '*.domain.com' syntax to match "
+        "any subdomain of the specified domain (e.g. '*.github.com' matches "
+        "'api.github.com' and 'raw.github.com' but not 'github.com' itself).",
+    )
+
+    @model_validator(mode="after")
+    def _validate_exactly_one_field(self) -> "DomainSelector":
+        if self.match_name and self.match_pattern:
+            raise ValueError(
+                "Exactly one of match_name or match_pattern must be set, not both"
+            )
+        if not self.match_name and not self.match_pattern:
+            raise ValueError("Exactly one of match_name or match_pattern must be set")
+        domain = self.match_name or self.match_pattern or ""
+        if not _DOMAIN_PATTERN.match(domain):
+            raise ValueError(
+                f"Invalid domain '{domain}'. "
+                "Must be an exact FQDN (e.g., api.openai.com) "
+                "or wildcard prefix (e.g., *.github.com). "
+                "URL schemes, ports, paths, IP addresses, "
+                "and bare wildcards are not allowed."
+            )
+        return self
+
+    model_config = {"extra": "forbid"}
+
+
+class EgressConfig(BaseModel):
+    """Configuration for network egress allow list.
+
+    Domains are specified as objects with either matchName (exact FQDN)
+    or matchPattern (wildcard prefix). This is a subset of the
+    downstream Cilium FQDN selector API.
+
+    Example:
+        network:
+          egress:
+            allow_domains:
+              - match_name: api.openai.com
+              - match_pattern: "*.github.com"
+    """
+
+    allow_domains: list[DomainSelector] = Field(
+        default_factory=list,
+        description="Domains allowed for egress as Cilium FQDN selectors.",
+    )
+
+    @field_validator("allow_domains")
+    @classmethod
+    def _validate_allow_domains(cls, v: list[DomainSelector]) -> list[DomainSelector]:
+        if len(v) > 50:
+            raise ValueError(
+                f"allow_domains cannot have more than 50 entries, got {len(v)}"
+            )
+        return v
+
+
+class NetworkConfig(BaseModel):
+    """Network configuration for an agent.
+
+    When present in dispatch.yaml, CiliumNetworkPolicies are created to
+    restrict the agent's outbound traffic to platform services and any
+    listed allow_domains.  When absent, all egress is unrestricted.
+
+    Example:
+        network:
+          egress:
+            allow_domains:
+              - match_name: api.openai.com
+              - match_pattern: "*.github.com"
+    """
+
+    egress: EgressConfig = Field(default_factory=EgressConfig)
+
+
 class DispatchConfig(BaseModel):
     """Configuration model for dispatch.yaml files.
 
@@ -416,6 +516,10 @@ class DispatchConfig(BaseModel):
         default_factory=ResourceConfig,
         description="Container resource limits (CPU and memory)",
     )
+    network: NetworkConfig | None = Field(
+        default=None,
+        description="Network egress restrictions. When set, CiliumNetworkPolicies restrict outbound traffic.",
+    )
 
     @field_validator("env")
     @classmethod
@@ -485,6 +589,16 @@ class DispatchConfig(BaseModel):
         }
         result["resources"] = {"limits": limits_dict}
 
+        if self.network is not None:
+            result["network"] = {
+                "egress": {
+                    "allow_domains": [
+                        d.model_dump(exclude_none=True)
+                        for d in self.network.egress.allow_domains
+                    ],
+                }
+            }
+
         return result
 
     model_config = {"populate_by_name": True}

{dispatch_agents-0.10.1 → dispatch_agents-0.12.2}/dispatch_agents/integrations/github/__init__.py

@@ -88,6 +88,10 @@ from typing import Any, ClassVar, Literal
 from pydantic import ConfigDict, Field
 
 from dispatch_agents.events import BasePayload
+from dispatch_agents.integrations.github.client import GitHubAppToken
+from dispatch_agents.integrations.github.client import (
+    get_github_app_token as _get_github_app_token,
+)
 from dispatch_agents.models import StrictBaseModel
 
 # =============================================================================
@@ -98,6 +102,16 @@ from dispatch_agents.models import StrictBaseModel
 GITHUB_TOPIC_PREFIX = "github."
 
 
+async def get_github_app_token() -> GitHubAppToken:
+    """Return a GitHub App installation token.
+
+    This package-level wrapper is the canonical public import path for GitHub
+    token retrieval and delegates to the lower-level client implementation.
+    """
+
+    return await _get_github_app_token()
+
+
 # =============================================================================
 # GitHubEvent Enum
 # =============================================================================
@@ -4056,6 +4070,9 @@ __all__ = [
     "GitHubIssuePullRequest",
     "GitHubChangeValue",
     "GitHubChanges",
+    # GitHub client
+    "get_github_app_token",
+    "GitHubAppToken",
     # Watch events
     "WatchBase",
     "WatchStarted",

dispatch_agents-0.12.2/dispatch_agents/integrations/github/client.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+import httpx
+
+from dispatch_agents.events import _get_auth_headers, _get_router_url
+
+# Module-level cache for the current agent process.
+# The SDK assumes a single agent run does not switch orgs or API keys in-process;
+# multi-org access is enforced by the backend, not modeled in this client cache.
+_cached_token: tuple[GitHubAppToken, datetime] | None = None
+
+_TOKEN_BUFFER_MINUTES = 5
+
+
+@dataclass
+class GitHubAppToken:
+    token: str
+    expires_at: datetime
+
+
+async def get_github_app_token() -> GitHubAppToken:
+    """Return a GitHub App installation token for use with any HTTP client.
+
+    Fetches a GitHub App installation token from the Dispatch backend. The token
+    is cached transparently; subsequent calls return the cached token until it is
+    near expiry (< 5 min), at which point a fresh token is fetched automatically.
+
+    Returns:
+        GitHubAppToken: Dataclass with ``token`` (str) and
+        ``expires_at`` (timezone-aware datetime) fields. Pass ``token`` as a
+        Bearer credential to any GitHub API client of your choice.
+
+    Raises:
+        RuntimeError: If DISPATCH_API_KEY environment variable is not set.
+        RuntimeError: If no GitHub installation is configured for this org (404).
+        RuntimeError: If authentication fails — check DISPATCH_API_KEY (401).
+        RuntimeError: If access is forbidden (403).
+        RuntimeError: If the backend returns an unexpected HTTP status code.
+
+    Note:
+        Refresh is lazy and call-time: a new token is fetched on the NEXT call
+        after the cached token nears expiry (<5 min remaining). Call
+        get_github_app_token() at the start of each handler invocation
+        rather than once at module load.
+
+        Network errors (httpx.ConnectError, httpx.TimeoutException) propagate
+        as-is and are not caught.
+
+    Examples:
+        Using PyGithub::
+
+            from github import Auth, Github
+            from dispatch_agents.integrations.github import get_github_app_token
+
+            tok = await get_github_app_token()
+            gh = Github(auth=Auth.Token(tok.token))
+            repo = gh.get_repo("my-org/my-repo")
+
+        Using httpx directly::
+
+            import httpx
+            from dispatch_agents.integrations.github import get_github_app_token
+
+            tok = await get_github_app_token()
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(
+                    "https://api.github.com/repos/my-org/my-repo",
+                    headers={"Authorization": f"Bearer {tok.token}"},
+                )
+    """
+    global _cached_token
+
+    if not os.getenv("DISPATCH_API_KEY"):
+        raise RuntimeError(
+            "DISPATCH_API_KEY environment variable is not set. "
+            "GitHub installation token requires an authenticated Dispatch agent."
+        )
+
+    if _cached_token is not None:
+        cached, expires_at = _cached_token
+        if expires_at >= datetime.now(UTC) + timedelta(minutes=_TOKEN_BUFFER_MINUTES):
+            return cached
+
+    url = _get_router_url() + "/api/unstable/integrations/github/installation-token"
+
+    async with httpx.AsyncClient() as http_client:
+        response = await http_client.post(
+            url, headers=_get_auth_headers(), timeout=10.0
+        )
+
+    if response.status_code == 401:
+        raise RuntimeError(
+            "GitHub installation token request failed: unauthorized. "
+            "Check that DISPATCH_API_KEY is valid."
+        )
+    if response.status_code == 403:
+        raise RuntimeError("GitHub installation token request failed: forbidden.")
+    if response.status_code == 404:
+        raise RuntimeError(
+            "No GitHub installation found for this organization. "
+            "Ensure the GitHub App is installed and configured in Dispatch."
+        )
+    if response.status_code != 200:
+        raise RuntimeError(
+            f"Failed to fetch GitHub installation token: "
+            f"backend returned HTTP {response.status_code}"
+        )
+
+    data = response.json()
+    token: str = data["token"]
+    expires_at = datetime.fromisoformat(data["expires_at"])
+    if expires_at.tzinfo is None:
+        expires_at = expires_at.replace(tzinfo=UTC)
+
+    result = GitHubAppToken(token=token, expires_at=expires_at)
+    _cached_token = (result, expires_at)
+    return result

{dispatch_agents-0.10.1 → dispatch_agents-0.12.2}/dispatch_agents/llm.py

@@ -470,7 +470,17 @@ class LLMClient:
                 headers=auth_headers,
                 timeout=600.0,  # 10min — matches ALB idle timeout for long-context LLM calls
             )
-            response.raise_for_status()
+            if response.status_code >= 400:
+                try:
+                    error_body = response.json()
+                    detail = error_body.get("detail", response.text)
+                except Exception:
+                    detail = response.text
+                raise httpx.HTTPStatusError(
+                    f"LLM inference failed ({response.status_code}): {detail}",
+                    request=response.request,
+                    response=response,
+                )
             data = response.json()
 
         # Parse tool calls if present

{dispatch_agents-0.10.1 → dispatch_agents-0.12.2}/dispatch_agents/proxy/server.py

@@ -764,7 +764,7 @@ async def _call_provider_directly_streaming(
 ) -> Response:
     """Call the LLM provider directly with streaming (fallback when backend has no config).
 
-    Uses raw httpx streaming (not litellm) since litellm is not available in the SDK.
+    Uses raw httpx streaming.
     Buffers SSE events for usage extraction and logs to /llm/log after stream completes.
     """
 
@@ -947,10 +947,10 @@ async def _proxy_passthrough(request: Request, provider_format: str) -> Response
         )
 
     # Build passthrough request for backend.
-    # provider_format is no longer sent; the backend derives it from path.
     backend_payload: dict[str, Any] = {
         "path": path,
         "method": method,
+        "provider_format": provider_format,
     }
     if body_dict is not None:
         backend_payload["body"] = body_dict

{dispatch_agents-0.10.1 → dispatch_agents-0.12.2}/examples/hello_world/agent.py

@@ -2,6 +2,7 @@
 
 import asyncio
 
+import aiohttp
 import dispatch_agents
 from dispatch_agents import BasePayload, fn, on
 from dispatch_agents.integrations.github import PullRequestReviewCommentCreated
@@ -11,7 +12,7 @@ from pydantic import Field, PositiveInt
 class GreetingPayload(BasePayload):
     """Input payload for greeting requests."""
 
-    subject: str = Field(description="The name or subject to greet")
+    subject: str = Field(default="World", description="The name or subject to greet")
 
 
 class GreetingResponse(BasePayload):
@@ -110,3 +111,51 @@ async def reverse(payload: ReverseRequest) -> ReverseResponse:
     """Reverse the provided text string."""
     print(f"Reversing: {payload.text!r}")
     return ReverseResponse(reversed_text=payload.text[::-1])
+
+
+class EgressTestRequest(BasePayload):
+    """Input for the egress test function."""
+
+    url: str = Field(
+        default="https://jsonplaceholder.typicode.com/todos/1",
+        description="URL to attempt to fetch",
+    )
+
+
+class EgressTestResponse(BasePayload):
+    """Output of the egress test function."""
+
+    success: bool = Field(description="Whether the request succeeded")
+    status_code: int | None = Field(
+        default=None, description="HTTP status code if successful"
+    )
+    body: str = Field(default="", description="Response body or error message")
+
+
+@fn()
+async def test_egress(payload: EgressTestRequest) -> EgressTestResponse:
+    """Test outbound HTTP connectivity by fetching a URL.
+
+    Useful for verifying network egress controls. When network.egress is
+    configured, this request will be blocked unless the target domain is
+    in allow_domains.
+    """
+    print(f"Testing egress to: {payload.url}")
+    try:
+        async with aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=10)
+        ) as session:
+            async with session.get(payload.url) as resp:
+                body = await resp.text()
+                print(f"Response: {resp.status} ({len(body)} bytes)")
+                return EgressTestResponse(
+                    success=True,
+                    status_code=resp.status,
+                    body=body[:1000],
+                )
+    except Exception as e:
+        print(f"Request failed: {type(e).__name__}: {e}")
+        return EgressTestResponse(
+            success=False,
+            body=f"{type(e).__name__}: {e}",
+        )