dispatch_agents 0.9.0__tar.gz

dispatch_agents-0.9.0/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "dispatch-agents",
+  "owner": {
+    "name": "Dispatch Agents Team",
+    "email": "dispatch-agents@datadoghq.com"
+  },
+  "metadata": {
+    "description": "Official plugins for building and managing Dispatch Agents"
+  },
+  "plugins": [
+    {
+      "name": "dispatch-agents",
+      "source": "./plugins/dispatch-agents",
+      "description": "Getting started skill and Dispatch Operator MCP server for building Dispatch Agents",
+      "version": "0.1.0",
+      "author": {
+        "name": "Dispatch Agents Team"
+      },
+      "keywords": ["dispatch", "agents", "mcp"]
+    }
+  ]
+}

dispatch_agents-0.9.0/.github/scripts/change_scope.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Classify whether the current ref includes release-relevant changes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from ci_git import (
+    fetch_main_branch_ref,
+    fetch_tags,
+    get_changed_files,
+    get_latest_tag,
+    get_merge_base,
+)
+
+
+@dataclass(frozen=True)
+class ChangeScopeResult:
+    ref_name: str
+    range_label: str
+    pyproject_baseline_ref: str | None
+    changed_files: tuple[str, ...]
+    source_changed: bool
+
+
+def parse_json_string_list(value: str) -> list[str]:
+    parsed = json.loads(value)
+    if not isinstance(parsed, list) or not all(
+        isinstance(item, str) for item in parsed
+    ):
+        raise ValueError("expected a JSON array of strings")
+    return parsed
+
+
+def is_release_relevant_source_path(
+    path: str,
+    *,
+    ignored_paths: set[str],
+    ignored_prefixes: tuple[str, ...],
+) -> bool:
+    if path in ignored_paths:
+        return False
+    return not path.startswith(ignored_prefixes)
+
+
+def classify_changed_files(
+    changed_files: list[str],
+    *,
+    ignored_paths: set[str],
+    ignored_prefixes: tuple[str, ...],
+) -> bool:
+    return any(
+        is_release_relevant_source_path(
+            path,
+            ignored_paths=ignored_paths,
+            ignored_prefixes=ignored_prefixes,
+        )
+        for path in changed_files
+    )
+
+
+def determine_change_scope(
+    *,
+    ref_name: str,
+    changed_files: list[str],
+    latest_tag: str | None,
+    feature_branch_base_ref: str | None,
+    ignored_paths: set[str],
+    ignored_prefixes: tuple[str, ...],
+) -> ChangeScopeResult:
+    if ref_name != "main":
+        if feature_branch_base_ref is None:
+            raise ValueError(
+                "feature_branch_base_ref is required for feature-branch mode"
+            )
+        return ChangeScopeResult(
+            ref_name=ref_name,
+            range_label=f"{feature_branch_base_ref}...HEAD",
+            pyproject_baseline_ref=feature_branch_base_ref,
+            changed_files=tuple(changed_files),
+            source_changed=classify_changed_files(
+                changed_files,
+                ignored_paths=ignored_paths,
+                ignored_prefixes=ignored_prefixes,
+            ),
+        )
+
+    range_label = (
+        f"{latest_tag}...HEAD" if latest_tag is not None else "tracked files in HEAD"
+    )
+    return ChangeScopeResult(
+        ref_name=ref_name,
+        range_label=range_label,
+        pyproject_baseline_ref=latest_tag,
+        changed_files=tuple(changed_files),
+        source_changed=classify_changed_files(
+            changed_files,
+            ignored_paths=ignored_paths,
+            ignored_prefixes=ignored_prefixes,
+        ),
+    )
+
+
+def get_feature_branch_base_ref() -> str:
+    fetch_main_branch_ref()
+    return get_merge_base("HEAD", "origin/main")
+
+
+def write_github_outputs(result: ChangeScopeResult) -> None:
+    output_path = os.environ.get("GITHUB_OUTPUT")
+    if not output_path:
+        return
+
+    outputs = {
+        "source_changed": str(result.source_changed).lower(),
+        "pyproject_baseline_ref": result.pyproject_baseline_ref or "",
+    }
+
+    with Path(output_path).open("a", encoding="utf-8") as file_obj:
+        for key, value in outputs.items():
+            file_obj.write(f"{key}={value}\n")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--ref-name",
+        required=True,
+        help="GitHub ref name for the current workflow run.",
+    )
+    parser.add_argument(
+        "--ignored-paths-json",
+        required=True,
+        help="JSON array of exact paths that do not count as release-relevant source changes.",
+    )
+    parser.add_argument(
+        "--ignored-prefixes-json",
+        required=True,
+        help="JSON array of path prefixes that do not count as release-relevant source changes.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    ignored_paths = set(parse_json_string_list(args.ignored_paths_json))
+    ignored_prefixes = tuple(parse_json_string_list(args.ignored_prefixes_json))
+
+    fetch_tags()
+
+    latest_tag = get_latest_tag()
+    if args.ref_name != "main":
+        feature_branch_base_ref = get_feature_branch_base_ref()
+        changed_files = get_changed_files(feature_branch_base_ref)
+    else:
+        feature_branch_base_ref = None
+        changed_files = get_changed_files(latest_tag)
+
+    result = determine_change_scope(
+        ref_name=args.ref_name,
+        changed_files=changed_files,
+        latest_tag=latest_tag,
+        feature_branch_base_ref=feature_branch_base_ref,
+        ignored_paths=ignored_paths,
+        ignored_prefixes=ignored_prefixes,
+    )
+    write_github_outputs(result)
+
+    print(f"Change scope ({args.ref_name})")
+    print(f"  range: {result.range_label}")
+    print(
+        f"  pyproject baseline: {result.pyproject_baseline_ref or '(latest tag baseline unavailable)'}"
+    )
+    print(f"  ignored paths: {sorted(ignored_paths)}")
+    print(f"  ignored prefixes: {list(ignored_prefixes)}")
+    print(f"  release-relevant source changed: {str(result.source_changed).lower()}")
+    if result.changed_files:
+        print("  compared files:")
+        for path in result.changed_files:
+            print(f"    - {path}")
+    else:
+        print("  compared files: (none)")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dispatch_agents-0.9.0/.github/scripts/ci_git.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Shared git and tag helpers for CI workflow scripts."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Iterable
+
+SEMVER_TAG_RE = re.compile(r"^v(\d+)\.(\d+)\.(\d+)$")
+
+
+def run_git(*args: str, check: bool = True) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        check=check,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip()
+
+
+def parse_tag(tag: str) -> tuple[int, int, int]:
+    match = SEMVER_TAG_RE.fullmatch(tag)
+    if not match:
+        raise ValueError(f"Unsupported tag format: {tag}")
+    return tuple(int(part) for part in match.groups())
+
+
+def filter_semver_tags(tags: Iterable[str]) -> list[str]:
+    valid_tags = [tag for tag in tags if SEMVER_TAG_RE.fullmatch(tag)]
+    return sorted(valid_tags, key=parse_tag)
+
+
+def fetch_tags() -> None:
+    subprocess.run(
+        ["git", "fetch", "--force", "--tags", "origin"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def fetch_main_branch_ref() -> None:
+    subprocess.run(
+        ["git", "fetch", "--no-tags", "origin", "main:refs/remotes/origin/main"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def get_latest_tag() -> str | None:
+    tags_output = run_git("tag", "--list", "v*")
+    tags = [line.strip() for line in tags_output.splitlines() if line.strip()]
+    valid_tags = filter_semver_tags(tags)
+    if not valid_tags:
+        return None
+    return valid_tags[-1]
+
+
+def get_merge_base(left_ref: str, right_ref: str) -> str:
+    return run_git("merge-base", left_ref, right_ref)
+
+
+def get_changed_files(diff_ref: str | None) -> list[str]:
+    if diff_ref is None:
+        output = run_git("ls-files")
+    else:
+        output = run_git(
+            "diff",
+            "--name-only",
+            "--diff-filter=ACDMRTUXB",
+            f"{diff_ref}...HEAD",
+        )
+    return [line.strip() for line in output.splitlines() if line.strip()]

dispatch_agents-0.9.0/.github/scripts/version_policy.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Enforce release version policy for CI workflows."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+SEMVER_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+from ci_git import fetch_tags, get_latest_tag, parse_tag
+
+
+@dataclass(frozen=True)
+class PolicyResult:
+    current_version: str
+    current_tag: str
+    latest_tag: str
+    source_changed: bool
+    requires_version_bump: bool
+    has_version_bump: bool
+    should_release: bool
+    relevant_pyproject_changed: bool
+    failure_reason: str | None
+
+
+def parse_version(version: str) -> tuple[int, int, int]:
+    match = SEMVER_VERSION_RE.fullmatch(version)
+    if not match:
+        raise ValueError(f"Unsupported version format: {version}")
+    return tuple(int(part) for part in match.groups())
+
+
+def compare_versions(current_version: str, latest_tag: str) -> int:
+    current = parse_version(current_version)
+    latest = parse_tag(latest_tag)
+    if current > latest:
+        return 1
+    if current < latest:
+        return -1
+    return 0
+
+
+def is_relevant_pyproject_change(
+    current_pyproject: dict[str, Any], baseline_pyproject: dict[str, Any] | None
+) -> bool:
+    if baseline_pyproject is None:
+        return False
+
+    current_project = dict(current_pyproject.get("project", {}))
+    baseline_project = dict(baseline_pyproject.get("project", {}))
+    current_project.pop("version", None)
+    baseline_project.pop("version", None)
+
+    current_hatch = current_pyproject.get("tool", {}).get("hatch", {}).get("build", {})
+    baseline_hatch = (
+        baseline_pyproject.get("tool", {}).get("hatch", {}).get("build", {})
+    )
+
+    return (
+        current_pyproject.get("build-system", {})
+        != baseline_pyproject.get("build-system", {})
+        or current_project != baseline_project
+        or current_hatch != baseline_hatch
+    )
+
+
+def evaluate_policy(
+    *,
+    source_changed: bool,
+    current_pyproject: dict[str, Any],
+    baseline_pyproject: dict[str, Any] | None,
+    latest_tag: str | None,
+) -> PolicyResult:
+    current_version = current_pyproject["project"]["version"]
+    current_tag = f"v{current_version}"
+    baseline_tag = latest_tag or "v0.0.0"
+    relevant_change = is_relevant_pyproject_change(
+        current_pyproject, baseline_pyproject
+    )
+    bump_required = source_changed or relevant_change
+
+    has_bump = compare_versions(current_version, baseline_tag) > 0
+    comparison = compare_versions(current_version, baseline_tag)
+    failure_reason: str | None = None
+
+    if comparison < 0:
+        failure_reason = (
+            f"Current version {current_tag} is behind latest release {baseline_tag}."
+        )
+    elif latest_tag is not None and bump_required and comparison <= 0:
+        failure_reason = (
+            "Changes require a semantic version bump, "
+            f"but {current_tag} is not greater than {baseline_tag}."
+        )
+
+    return PolicyResult(
+        current_version=current_version,
+        current_tag=current_tag,
+        latest_tag=baseline_tag,
+        source_changed=source_changed,
+        requires_version_bump=bump_required,
+        has_version_bump=has_bump,
+        should_release=has_bump,
+        relevant_pyproject_changed=relevant_change,
+        failure_reason=failure_reason,
+    )
+
+
+def load_pyproject(path: Path) -> dict[str, Any]:
+    with path.open("rb") as file_obj:
+        return tomllib.load(file_obj)
+
+
+def load_pyproject_from_ref(ref: str | None, repo_root: Path) -> dict[str, Any] | None:
+    if ref is None:
+        return None
+
+    result = subprocess.run(
+        ["git", "show", f"{ref}:pyproject.toml"],
+        check=False,
+        capture_output=True,
+        text=True,
+        cwd=repo_root,
+    )
+    if result.returncode != 0:
+        return None
+    return tomllib.loads(result.stdout)
+
+
+def write_github_outputs(result: PolicyResult) -> None:
+    output_path = os.environ.get("GITHUB_OUTPUT")
+    if not output_path:
+        return
+
+    outputs = {
+        "current_version": result.current_version,
+        "current_tag": result.current_tag,
+        "latest_tag": result.latest_tag,
+        "requires_version_bump": str(result.requires_version_bump).lower(),
+        "has_version_bump": str(result.has_version_bump).lower(),
+        "relevant_pyproject_changed": str(result.relevant_pyproject_changed).lower(),
+        "should_release": str(result.should_release).lower(),
+    }
+
+    with Path(output_path).open("a", encoding="utf-8") as file_obj:
+        for key, value in outputs.items():
+            file_obj.write(f"{key}={value}\n")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--source-changed",
+        choices=("true", "false"),
+        required=True,
+        help="Whether the workflow determined that release-relevant non-pyproject files changed.",
+    )
+    parser.add_argument(
+        "--pyproject-baseline-ref",
+        default="",
+        help="Git ref to use as the pyproject.toml comparison baseline. Defaults to the latest release tag when omitted.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    repo_root = Path.cwd()
+    fetch_tags()
+
+    latest_tag = get_latest_tag()
+    current_pyproject = load_pyproject(repo_root / "pyproject.toml")
+    pyproject_baseline_ref = args.pyproject_baseline_ref or latest_tag
+    baseline_pyproject = load_pyproject_from_ref(pyproject_baseline_ref, repo_root)
+    source_changed = args.source_changed == "true"
+
+    result = evaluate_policy(
+        source_changed=source_changed,
+        current_pyproject=current_pyproject,
+        baseline_pyproject=baseline_pyproject,
+        latest_tag=latest_tag,
+    )
+    write_github_outputs(result)
+
+    print("Version policy check")
+    print(f"  latest tag: {result.latest_tag}")
+    print(f"  current tag: {result.current_tag}")
+    print(f"  pyproject baseline: {pyproject_baseline_ref or '(none)'}")
+    print(f"  source changed: {str(result.source_changed).lower()}")
+    print(f"  requires bump: {str(result.requires_version_bump).lower()}")
+    print(f"  should release: {str(result.should_release).lower()}")
+
+    if result.failure_reason:
+        print(result.failure_reason, file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dispatch_agents-0.9.0/.github/tests/test_change_scope.py

@@ -0,0 +1,159 @@
+"""Tests for the CI change scope helper."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+MODULE_PATH = (
+    Path(__file__).resolve().parents[2] / ".github" / "scripts" / "change_scope.py"
+)
+MODULE_NAME = "dispatch_agents_ci_change_scope"
+sys.path.insert(0, str(MODULE_PATH.parent))
+
+IGNORED_PATHS = {
+    "README.md",
+    "CONTRIBUTING.md",
+    "NOTICE",
+    "uv.lock",
+    "pyproject.toml",
+}
+IGNORED_PREFIXES = (".github/", "tests/", "examples/", "plugins/", "LICENSE")
+
+spec = importlib.util.spec_from_file_location(MODULE_NAME, MODULE_PATH)
+assert spec is not None
+assert spec.loader is not None
+change_scope = importlib.util.module_from_spec(spec)
+sys.modules[MODULE_NAME] = change_scope
+spec.loader.exec_module(change_scope)
+
+
+def test_docs_and_workflow_changes_are_not_release_relevant():
+    assert (
+        change_scope.classify_changed_files(
+            [
+                "README.md",
+                ".github/workflows/feature-branch.yml",
+                "tests/test_config.py",
+            ],
+            ignored_paths=set(IGNORED_PATHS),
+            ignored_prefixes=IGNORED_PREFIXES,
+        )
+        is False
+    )
+
+
+def test_pyproject_change_is_deferred_to_semantic_diff():
+    assert (
+        change_scope.classify_changed_files(
+            ["pyproject.toml"],
+            ignored_paths=set(IGNORED_PATHS),
+            ignored_prefixes=IGNORED_PREFIXES,
+        )
+        is False
+    )
+
+
+def test_sdk_change_is_release_relevant():
+    assert (
+        change_scope.classify_changed_files(
+            ["dispatch_agents/instrument.py"],
+            ignored_paths=set(IGNORED_PATHS),
+            ignored_prefixes=IGNORED_PREFIXES,
+        )
+        is True
+    )
+
+
+def test_unknown_top_level_path_is_conservatively_relevant():
+    assert (
+        change_scope.classify_changed_files(
+            ["new_surface/config.json"],
+            ignored_paths=set(IGNORED_PATHS),
+            ignored_prefixes=IGNORED_PREFIXES,
+        )
+        is True
+    )
+
+
+def test_custom_ignored_prefixes_make_policy_explicit():
+    assert (
+        change_scope.classify_changed_files(
+            ["docs/release-notes.md"],
+            ignored_paths=set(),
+            ignored_prefixes=("docs/",),
+        )
+        is False
+    )
+
+
+def test_feature_branch_scope_uses_branch_base_for_pyproject():
+    result = change_scope.determine_change_scope(
+        ref_name="feature/foo",
+        changed_files=[".github/workflows/release.yml"],
+        latest_tag="v0.7.3",
+        feature_branch_base_ref="abc123",
+        ignored_paths=set(IGNORED_PATHS),
+        ignored_prefixes=IGNORED_PREFIXES,
+    )
+
+    assert result.range_label == "abc123...HEAD"
+    assert result.pyproject_baseline_ref == "abc123"
+    assert result.source_changed is False
+
+
+def test_release_scope_uses_latest_tag():
+    result = change_scope.determine_change_scope(
+        ref_name="main",
+        changed_files=["dispatch_agents/instrument.py"],
+        latest_tag="v0.7.3",
+        feature_branch_base_ref=None,
+        ignored_paths=set(IGNORED_PATHS),
+        ignored_prefixes=IGNORED_PREFIXES,
+    )
+
+    assert result.range_label == "v0.7.3...HEAD"
+    assert result.pyproject_baseline_ref == "v0.7.3"
+    assert result.source_changed is True
+
+
+def test_feature_branch_scope_requires_base_ref():
+    with pytest.raises(ValueError):
+        change_scope.determine_change_scope(
+            ref_name="feature/foo",
+            changed_files=[],
+            latest_tag="v0.7.3",
+            feature_branch_base_ref=None,
+            ignored_paths=set(IGNORED_PATHS),
+            ignored_prefixes=IGNORED_PREFIXES,
+        )
+
+
+def test_parse_json_string_list_rejects_non_string_lists():
+    with pytest.raises(ValueError):
+        change_scope.parse_json_string_list('["ok", 1]')
+
+
+def test_parse_args_requires_explicit_policy_values(monkeypatch):
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "change_scope.py",
+            "--ref-name",
+            "main",
+            "--ignored-paths-json",
+            '["README.md"]',
+            "--ignored-prefixes-json",
+            '[".github/"]',
+        ],
+    )
+
+    args = change_scope.parse_args()
+
+    assert args.ref_name == "main"
+    assert args.ignored_paths_json == '["README.md"]'
+    assert args.ignored_prefixes_json == '[".github/"]'