dispatch_agents 0.12.2__tar.gz → 0.13.3__tar.gz

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

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

dispatch_agents-0.13.3/RELEASE_NOTES.md

@@ -0,0 +1,2 @@
+## Bug Fixes
+- Custom `base_image` configurations are now explicitly rejected with an error rather than silently ignored, providing clearer feedback when unsupported options are supplied.

{dispatch_agents-0.12.2 → dispatch_agents-0.13.3}/dispatch_agents/__init__.py

@@ -162,6 +162,7 @@ def _dev_mode_audit_hook(event: str, args: tuple) -> None:
 
 
 from .agent_service import AgentServiceClient
+from .config import _runtime as config
 from .events import (
     HANDLER_METADATA,
     REGISTERED_HANDLERS,
@@ -208,6 +209,8 @@ from .models import (
 )
 
 __all__ = [
+    # runtime config
+    "config",
     # storage and dev mode isolation
     "get_data_dir",
     "DisallowedWriteError",

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

@@ -433,7 +433,6 @@ class DispatchConfig(BaseModel):
         namespace: skunkworks
         agent_name: my-agent
         entrypoint: agent.py
-        base_image: python:3.13-slim
         env:
           LOG_LEVEL: debug
           MY_APP_MODE: production
@@ -464,7 +463,10 @@ class DispatchConfig(BaseModel):
     )
     base_image: str | None = Field(
         default=None,
-        description="Base Docker image for the agent container",
+        description=(
+            "Currently only python:3.13-slim is supported; defaults to it "
+            "when omitted. Other values are rejected at deploy time."
+        ),
     )
     system_packages: list[str] | None = Field(
         default=None,
@@ -500,6 +502,49 @@ class DispatchConfig(BaseModel):
             raise ValueError(f"All env values must be strings. {examples}")
         return v
 
+    vars: dict[str, Any] | None = Field(
+        default=None,
+        description="Configuration variables accessible at runtime via dispatch_agents.config.vars. "
+        "Unlike env, these are NOT injected as environment variables. "
+        "Supports any YAML-serializable type. Use {value: <any>, description: <str>} "
+        "to attach descriptions for the UI.",
+    )
+
+    @field_validator("vars", mode="before")
+    @classmethod
+    def _validate_vars(cls, v: dict | None) -> dict[str, Any] | None:
+        """Validate vars format.
+
+        Non-dict values (str, int, float, bool, list, None) are allowed as-is.
+        Dict values must use the described-var shape:
+        ``{value: <any>, description?: <str>}``. Other dicts are rejected
+        because ``value`` and ``description`` are reserved keywords — silently
+        treating arbitrary dicts as plain values would let a caller
+        accidentally collide with the described-var schema.
+        """
+        if not v or not isinstance(v, dict):
+            return v
+        _DESCRIBED_KEYS = {"value", "description"}
+        for key, val in v.items():
+            if not isinstance(val, dict):
+                continue
+            if "value" not in val:
+                raise ValueError(
+                    f"Var '{key}' is a dict without a 'value' key. Dict values "
+                    "must use the described-var shape "
+                    "{value: <any>, description?: <str>}. To store structured "
+                    "data, nest it under 'value'."
+                )
+            extra = set(val.keys()) - _DESCRIBED_KEYS
+            if extra:
+                raise ValueError(
+                    f"Var '{key}' has unexpected keys {sorted(extra)}. Dict "
+                    "values may only use the described-var shape "
+                    "{value: <any>, description?: <str>}. To store structured "
+                    "data, nest it under 'value'."
+                )
+        return v
+
     secrets: list[SecretConfig] | None = Field(
         default=None,
         description="Secrets to inject as environment variables",
@@ -573,10 +618,14 @@ class DispatchConfig(BaseModel):
             result["local_dependencies"] = self.local_dependencies
         if self.env:
             result["env"] = dict(self.env)
+        if self.vars:
+            result["vars"] = dict(self.vars)
         if self.secrets:
             result["secrets"] = [
                 {"name": s.name, "secret_id": s.secret_id} for s in self.secrets
             ]
+        if self.mcp_servers:
+            result["mcp_servers"] = [{"server": m.server} for m in self.mcp_servers]
         if self.volumes:
             result["volumes"] = [
                 {"name": v.name, "mountPath": v.mount_path, "mode": v.mode.value}
@@ -602,3 +651,117 @@ class DispatchConfig(BaseModel):
         return result
 
     model_config = {"populate_by_name": True}
+
+
+# ---------------------------------------------------------------------------
+# Runtime config singleton
+# ---------------------------------------------------------------------------
+
+import functools as _functools
+
+_DISPATCH_YAML_PATH = "/app/dispatch.yaml"
+
+
+@_functools.lru_cache(maxsize=1)
+def _load_runtime_config() -> "DispatchConfig":
+    """Load dispatch.yaml once and cache the parsed DispatchConfig.
+
+    Falls back to an empty DispatchConfig when the file is absent
+    (dev mode or non-containerized runs). Namespace and agent_name
+    additionally fall back to DISPATCH_NAMESPACE / DISPATCH_AGENT_NAME
+    env vars so local ``dispatch agent dev`` runs work transparently.
+    """
+    import yaml as _yaml
+
+    path = os.environ.get("DISPATCH_CONFIG_PATH", _DISPATCH_YAML_PATH)
+    raw: dict = {}
+    if os.path.exists(path):
+        with open(path, encoding="utf-8") as f:
+            raw = _yaml.safe_load(f) or {}
+
+    cfg = DispatchConfig.model_validate(raw)
+
+    # Env-var fallbacks for identity fields used outside containers
+    updates: dict[str, Any] = {}
+    if cfg.namespace is None:
+        ns = os.environ.get("DISPATCH_NAMESPACE")
+        if ns:
+            updates["namespace"] = ns
+    if cfg.agent_name is None:
+        name = os.environ.get("DISPATCH_AGENT_NAME")
+        if name:
+            updates["agent_name"] = name
+    if updates:
+        cfg = cfg.model_copy(update=updates)
+
+    return cfg
+
+
+_DESCRIBED_VAR_KEYS = frozenset({"value", "description"})
+
+
+def _is_described_var(val: Any) -> bool:
+    """Check if a value is a described var ({value, description}) vs a plain dict."""
+    return (
+        isinstance(val, dict)
+        and "value" in val
+        and set(val.keys()) <= _DESCRIBED_VAR_KEYS
+    )
+
+
+def _unwrap_vars(raw: dict[str, Any] | None) -> dict[str, Any]:
+    """Unwrap described vars ({value, description}) to plain values.
+
+    Plain dicts (with keys outside {value, description}) are passed through as-is.
+    """
+    if not raw:
+        return {}
+    result: dict[str, Any] = {}
+    for key, val in raw.items():
+        if _is_described_var(val):
+            result[key] = val["value"]
+        else:
+            result[key] = val
+    return result
+
+
+def _extract_var_descriptions(raw: dict[str, Any] | None) -> dict[str, str]:
+    """Extract description strings from described vars."""
+    if not raw:
+        return {}
+    result: dict[str, str] = {}
+    for key, val in raw.items():
+        if _is_described_var(val) and "description" in val:
+            result[key] = val["description"]
+    return result
+
+
+class _RuntimeConfig:
+    """Proxy that exposes dispatch.yaml fields at runtime.
+
+    Usage::
+
+        from dispatch_agents import config
+
+        config.namespace                     # str | None
+        config.agent_name                    # str | None
+        config.vars["temperature"]           # 0.7 (unwrapped)
+        config.vars.get("missing")           # None
+        config.vars_descriptions["max_turns"] # "Maximum agent turns"
+    """
+
+    @property
+    def vars(self) -> dict[str, Any]:
+        """Return unwrapped vars dict (described vars return just the value)."""
+        return _unwrap_vars(_load_runtime_config().vars)
+
+    @property
+    def vars_descriptions(self) -> dict[str, str]:
+        """Return descriptions for vars that have them."""
+        return _extract_var_descriptions(_load_runtime_config().vars)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(_load_runtime_config(), name)
+
+
+_runtime = _RuntimeConfig()

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

@@ -83,9 +83,9 @@ GitHub Topics:
 
 from __future__ import annotations
 
-from typing import Any, ClassVar, Literal
+from typing import Any, ClassVar, Literal, Self
 
-from pydantic import ConfigDict, Field
+from pydantic import ConfigDict, Field, StrictInt, model_validator
 
 from dispatch_agents.events import BasePayload
 from dispatch_agents.integrations.github.client import GitHubAppToken
@@ -209,12 +209,12 @@ class GitHubRepository(GitHubModel):
     description: str | None = Field(default=None, description="Repository description")
     fork: bool = Field(default=False, description="Whether this is a fork")
     url: str | None = Field(default=None, description="API URL")
-    created_at: str | None = Field(
-        default=None, description="ISO8601 creation timestamp"
+    created_at: StrictInt | str = Field(
+        description="Creation timestamp (Unix epoch int or ISO8601 string)",
     )
     updated_at: str | None = Field(default=None, description="ISO8601 update timestamp")
-    pushed_at: str | None = Field(
-        default=None, description="ISO8601 last push timestamp"
+    pushed_at: StrictInt | str | None = Field(
+        description="Last push timestamp (Unix epoch int, ISO8601 string, or null)",
     )
     homepage: str | None = Field(default=None, description="Homepage URL")
     size: int = Field(default=0, description="Repository size in KB")
@@ -490,7 +490,7 @@ class GitHubCommitUser(GitHubModel):
     """Git user information (author/committer)."""
 
     name: str = Field(description="Git user name")
-    email: str = Field(description="Git user email")
+    email: str | None = Field(description="Git user email")
     username: str | None = Field(default=None, description="GitHub username if linked")
     date: str | None = Field(default=None, description="ISO8601 timestamp")
 
@@ -906,20 +906,38 @@ class PullRequestUnassigned(PullRequestBase):
     assignee: GitHubUser = Field(description="User who was unassigned")
 
 
-class PullRequestReviewRequested(PullRequestBase):
+class PullRequestReviewTargetBase(PullRequestBase):
+    """Base payload for pull_request review target events."""
+
+    requested_reviewer: GitHubUser | None = Field(
+        default=None,
+        description="User requested for review (absent when a team is requested)",
+    )
+    requested_team: GitHubTeam | None = Field(
+        default=None,
+        description="Team requested for review (absent when a user is requested)",
+    )
+
+    @model_validator(mode="after")
+    def validate_review_target(self) -> Self:
+        """Require exactly one review target field."""
+        if (self.requested_reviewer is None) == (self.requested_team is None):
+            raise ValueError(
+                "Exactly one of requested_reviewer or requested_team must be provided"
+            )
+        return self
+
+
+class PullRequestReviewRequested(PullRequestReviewTargetBase):
     """Payload for github.pull_request.review_requested events."""
 
     _dispatch_topic: ClassVar[str] = "github.pull_request.review_requested"
-    requested_reviewer: GitHubUser = Field(description="User requested for review")
 
 
-class PullRequestReviewRequestRemoved(PullRequestBase):
+class PullRequestReviewRequestRemoved(PullRequestReviewTargetBase):
     """Payload for github.pull_request.review_request_removed events."""
 
     _dispatch_topic: ClassVar[str] = "github.pull_request.review_request_removed"
-    requested_reviewer: GitHubUser = Field(
-        description="User whose review request was removed"
-    )
 
 
 class PullRequestReadyForReview(PullRequestBase):

{dispatch_agents-0.12.2 → dispatch_agents-0.13.3}/dispatch_agents/models.py

@@ -19,6 +19,13 @@ from typing import Annotated, Any, Literal, TypeAlias
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+_IDENTIFIER_PATTERN = r"^[a-zA-Z0-9._-]+$"
+_IDENTIFIER_MAX_LENGTH = 128
+Identifier: TypeAlias = Annotated[
+    str,
+    Field(min_length=1, max_length=_IDENTIFIER_MAX_LENGTH, pattern=_IDENTIFIER_PATTERN),
+]
+
 
 def get_now_utc() -> str:
     """Get the current UTC time in ISO8601 format."""
@@ -391,7 +398,7 @@ class AgentFunction(StrictBaseModel):
     the triggers that can invoke it (topics, schedules, etc.).
     """
 
-    name: str = Field(description="Handler function name")
+    name: Identifier = Field(description="Handler function name")
     description: str | None = Field(
         default=None, description="Handler docstring or description"
     )
@@ -627,9 +634,9 @@ class PublishEventBody(StrictBaseModel):
 class SubscriptionBody(StrictBaseModel):
     """Request body for agent subscription management."""
 
-    topics: list[str]
-    agent_name: str
-    functions: list[AgentFunction] | None = None
+    topics: list[Identifier] = Field(default_factory=list)
+    agent_name: Identifier
+    functions: list[AgentFunction] = Field(min_length=1)
 
 
 class EventRequest(StrictBaseModel):

{dispatch_agents-0.12.2 → dispatch_agents-0.13.3}/examples/company-researcher/dispatch.yaml

@@ -1,5 +1,4 @@
 namespace: examples
 entrypoint: agent.py
-base_image: python:3.13-slim
 system_packages: []
 agent_name: company-researcher

{dispatch_agents-0.12.2 → dispatch_agents-0.13.3}/examples/conversational-agent/dispatch.yaml

@@ -1,5 +1,4 @@
 namespace: examples
 entrypoint: agent.py
-base_image: python:3.13-slim
 system_packages: []
 agent_name: conversational-agent

{dispatch_agents-0.12.2 → dispatch_agents-0.13.3}/examples/daily-digest/dispatch.yaml

@@ -1,5 +1,4 @@
 namespace: examples
 entrypoint: agent.py
-base_image: python:3.13-slim
 system_packages: []
 agent_name: daily-digest

{dispatch_agents-0.12.2 → dispatch_agents-0.13.3}/examples/deep-research/dispatch.yaml

@@ -1,6 +1,5 @@
 namespace: examples
 entrypoint: agent.py
-base_image: python:3.13-slim
 system_packages: []
 agent_name: deep-research
 secrets:

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

@@ -1,13 +1,20 @@
 """Generated agent entrypoint."""
 
 import asyncio
+import logging
+import os
 
 import aiohttp
 import dispatch_agents
 from dispatch_agents import BasePayload, fn, on
-from dispatch_agents.integrations.github import PullRequestReviewCommentCreated
+from dispatch_agents.integrations.github import (
+    CheckSuiteCompleted,
+    PullRequestReviewCommentCreated,
+)
 from pydantic import Field, PositiveInt
 
+logger = logging.getLogger(__name__)
+
 
 class GreetingPayload(BasePayload):
     """Input payload for greeting requests."""
@@ -30,7 +37,7 @@ async def greet(payload: GreetingPayload) -> GreetingResponse:
     - Typed output serialization (returns GreetingResponse)
     - Automatic schema extraction for API documentation
     """
-    print(f"Handling greet request for: {payload.subject}")
+    logger.info("Handling greet request for: %s", payload.subject)
 
     # Validate that subject field exists - ValueError is non-retryable
     if not payload.subject:
@@ -60,13 +67,13 @@ class SleepResponse(BasePayload):
 @dispatch_agents.on(topic="sleep")
 async def sleep(payload: SleepRequest) -> SleepResponse:
     """Sleep for the specified duration, logging countdown progress."""
-    print(f"Starting sleep for {payload.duration_seconds} seconds")
+    logger.info("Starting sleep for %s seconds", payload.duration_seconds)
 
     for remaining in range(payload.duration_seconds, 0, -1):
-        print(f"Countdown: {remaining} seconds remaining")
+        logger.info("Countdown: %s seconds remaining", remaining)
         await asyncio.sleep(1)
 
-    print("Sleep completed")
+    logger.info("Sleep completed")
     return SleepResponse(seconds_slept=payload.duration_seconds)
 
 
@@ -83,9 +90,9 @@ async def on_pr_review_comment(
     event: PullRequestReviewCommentCreated,
 ) -> PRReviewCommentResponse:
     """Handle GitHub PR review comment created events."""
-    print(f"Received PR review comment from {event.comment.user.login}")
-    print(f"Comment body: {event.comment.body[:100]}...")
-    print(f"PR: {event.pull_request.title}")
+    logger.info("Received PR review comment from %s", event.comment.user.login)
+    logger.info("Comment body: %.100s...", event.comment.body)
+    logger.info("PR: %s", event.pull_request.title)
 
     return PRReviewCommentResponse(
         repo=event.repository.full_name,
@@ -94,6 +101,34 @@ async def on_pr_review_comment(
     )
 
 
+class CheckSuiteCompletedResponse(BasePayload):
+    """Response for check_suite.completed events."""
+
+    repo: str | None = Field(description="Repository full name (owner/repo)")
+    head_sha: str = Field(description="Head commit SHA of the suite")
+    conclusion: str | None = Field(
+        description="Suite conclusion (success, failure, ...)"
+    )
+
+
+@on(github_event=CheckSuiteCompleted)
+async def on_check_suite_completed(
+    event: CheckSuiteCompleted,
+) -> CheckSuiteCompletedResponse:
+    """Handle GitHub check_suite.completed events."""
+    logger.info(
+        "Check suite completed: repo=%s sha=%s conclusion=%s",
+        event.repository.full_name if event.repository else None,
+        event.check_suite.head_sha,
+        event.check_suite.conclusion,
+    )
+    return CheckSuiteCompletedResponse(
+        repo=event.repository.full_name if event.repository else None,
+        head_sha=event.check_suite.head_sha,
+        conclusion=event.check_suite.conclusion,
+    )
+
+
 class ReverseRequest(BasePayload):
     """Input for the reverse function."""
 
@@ -109,10 +144,68 @@ class ReverseResponse(BasePayload):
 @fn()
 async def reverse(payload: ReverseRequest) -> ReverseResponse:
     """Reverse the provided text string."""
-    print(f"Reversing: {payload.text!r}")
+    logger.info("Reversing: %r", payload.text)
     return ReverseResponse(reversed_text=payload.text[::-1])
 
 
+class StorageWriteRequest(BasePayload):
+    """Input for writing to persistent storage."""
+
+    key: str = Field(description="Filename to write")
+    value: str = Field(description="Content to write")
+
+
+class StorageWriteResponse(BasePayload):
+    """Output of storage write."""
+
+    path: str = Field(description="Full path of the written file")
+
+
+def _safe_data_path(key: str) -> str:
+    """Resolve a key to a path under /data, rejecting traversal attempts."""
+    path = os.path.abspath(os.path.join("/data", key))
+    if not path.startswith("/data/"):
+        raise ValueError("Invalid key: must resolve within /data")
+    return path
+
+
+@fn()
+async def storage_write(payload: StorageWriteRequest) -> StorageWriteResponse:
+    """Write a value to persistent storage at /data."""
+    path = _safe_data_path(payload.key)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as f:
+        f.write(payload.value)
+    logger.info("Wrote %s bytes to %s", len(payload.value), path)
+    return StorageWriteResponse(path=path)
+
+
+class StorageReadRequest(BasePayload):
+    """Input for reading from persistent storage."""
+
+    key: str = Field(description="Filename to read")
+
+
+class StorageReadResponse(BasePayload):
+    """Output of storage read."""
+
+    value: str | None = Field(description="File content, or null if not found")
+    exists: bool = Field(description="Whether the file exists")
+
+
+@fn()
+async def storage_read(payload: StorageReadRequest) -> StorageReadResponse:
+    """Read a value from persistent storage at /data."""
+    path = _safe_data_path(payload.key)
+    if os.path.exists(path):
+        with open(path) as f:
+            value = f.read()
+        logger.info("Read %s bytes from %s", len(value), path)
+        return StorageReadResponse(value=value, exists=True)
+    logger.info("File not found: %s", path)
+    return StorageReadResponse(value=None, exists=False)
+
+
 class EgressTestRequest(BasePayload):
     """Input for the egress test function."""
 
@@ -140,21 +233,21 @@ async def test_egress(payload: EgressTestRequest) -> EgressTestResponse:
     configured, this request will be blocked unless the target domain is
     in allow_domains.
     """
-    print(f"Testing egress to: {payload.url}")
+    logger.info("Testing egress to: %s", 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)")
+                logger.info("Response: %s (%s bytes)", resp.status, len(body))
                 return EgressTestResponse(
                     success=True,
                     status_code=resp.status,
                     body=body[:1000],
                 )
     except Exception as e:
-        print(f"Request failed: {type(e).__name__}: {e}")
+        logger.info("Request failed: %s: %s", type(e).__name__, e)
         return EgressTestResponse(
             success=False,
             body=f"{type(e).__name__}: {e}",

dispatch_agents-0.13.3/examples/hello_world/dispatch.yaml

@@ -0,0 +1,16 @@
+namespace: examples
+entrypoint: agent.py
+system_packages: []
+agent_name: hello-world
+volumes:
+- name: data
+  mountPath: /data
+  mode: read_write_many
+resources:
+  limits:
+    cpu: 250m
+    memory: 2Gi
+network:
+  egress:
+    allow_domains:
+    - match_name: jsonplaceholder.typicode.com