agent-dispatch 0.1.0__py3-none-any.whl

agent_dispatch/__init__.py

@@ -0,0 +1,3 @@
+"""agent-dispatch: Delegate tasks between Claude Code agents across projects."""
+
+__version__ = "0.1.0"

agent_dispatch/cache.py

@@ -0,0 +1,91 @@
+"""TTL-based in-memory cache for dispatch results."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import threading
+import time
+
+from .models import DispatchResult
+
+logger = logging.getLogger(__name__)
+
+
+class DispatchCache:
+    """Thread-safe TTL cache for dispatch results.
+
+    Keyed on (agent, task, context) — identical requests within the TTL
+    window return the cached result without spawning a new subprocess.
+    """
+
+    def __init__(self, ttl: int = 300) -> None:
+        self._ttl = ttl
+        self._store: dict[str, tuple[float, DispatchResult]] = {}
+        self._lock = threading.Lock()
+        self._hits = 0
+        self._misses = 0
+
+    @staticmethod
+    def _make_key(agent: str, task: str, context: str | None) -> str:
+        canonical = json.dumps(
+            {"agent": agent, "task": task, "context": context or ""},
+            sort_keys=True,
+        )
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    def get(self, agent: str, task: str, context: str | None = None) -> DispatchResult | None:
+        key = self._make_key(agent, task, context)
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                self._misses += 1
+                return None
+            ts, result = entry
+            if time.monotonic() - ts > self._ttl:
+                del self._store[key]
+                self._misses += 1
+                return None
+            self._hits += 1
+            return result
+
+    def put(
+        self,
+        agent: str,
+        task: str,
+        result: DispatchResult,
+        context: str | None = None,
+    ) -> None:
+        if not result.success:
+            return  # don't cache failures
+        key = self._make_key(agent, task, context)
+        with self._lock:
+            self._store[key] = (time.monotonic(), result)
+
+    def clear(self) -> int:
+        with self._lock:
+            count = len(self._store)
+            self._store.clear()
+            self._hits = 0
+            self._misses = 0
+            return count
+
+    def evict_expired(self) -> int:
+        now = time.monotonic()
+        with self._lock:
+            expired = [k for k, (ts, _) in self._store.items() if now - ts > self._ttl]
+            for k in expired:
+                del self._store[k]
+            return len(expired)
+
+    def stats(self) -> dict:
+        with self._lock:
+            total = self._hits + self._misses
+            return {
+                "size": len(self._store),
+                "hits": self._hits,
+                "misses": self._misses,
+                "hit_rate": round(self._hits / total, 3) if total else 0.0,
+                "ttl": self._ttl,
+            }

agent_dispatch/cli.py

@@ -0,0 +1,178 @@
+"""CLI: init, add, remove, list, test, serve."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import click
+
+from .config import auto_describe, config_path, load_config, save_config
+from .models import AgentConfig, DispatchConfig, validate_agent_name
+
+
+@click.group()
+@click.version_option(package_name="agent-dispatch")
+def cli() -> None:
+    """Delegate tasks between Claude Code agents across projects."""
+
+
+@cli.command()
+def init() -> None:
+    """Create config file and register MCP server with Claude Code."""
+    cp = config_path()
+
+    # Create config with example
+    if cp.exists():
+        click.echo(f"Config already exists: {cp}")
+    else:
+        cp.parent.mkdir(parents=True, exist_ok=True)
+        example = DispatchConfig()
+        save_config(example, cp)
+        click.echo(f"Created config: {cp}")
+
+    # Register MCP server with Claude Code
+    if shutil.which("claude") is None:
+        click.echo("Warning: claude CLI not found. Register MCP server manually.")
+        return
+
+    agent_dispatch_cmd = shutil.which("agent-dispatch")
+    if agent_dispatch_cmd is None:
+        click.echo(
+            "Warning: agent-dispatch not found in PATH. "
+            "Run 'pip install -e .' first, then re-run 'agent-dispatch init'."
+        )
+        return
+
+    mcp_config = json.dumps({
+        "type": "stdio",
+        "command": agent_dispatch_cmd,
+        "args": ["serve"],
+    })
+
+    result = subprocess.run(
+        ["claude", "mcp", "add-json", "agent-dispatch", mcp_config, "--scope", "user"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode == 0:
+        click.echo("Registered MCP server with Claude Code (user scope).")
+        click.echo("\nNext steps:")
+        click.echo("  agent-dispatch add <name> <directory>  # add your first agent")
+        click.echo("  agent-dispatch list                    # verify agents")
+        click.echo("  agent-dispatch test <name>             # test it works")
+    else:
+        click.echo(f"Failed to register MCP server: {result.stderr.strip()}")
+        click.echo("You can register manually in ~/.claude/settings.json:")
+        click.echo(f'  "mcpServers": {{ "agent-dispatch": {mcp_config} }}')
+
+
+@cli.command()
+@click.argument("name")
+@click.argument("directory", type=click.Path(exists=True, file_okay=False, resolve_path=True))
+@click.option("-d", "--description", default=None, help="Agent description. Auto-generated if omitted.")
+@click.option("--timeout", default=300, help="Timeout in seconds (default: 300).")
+@click.option("--model", default=None, help="Model override for this agent.")
+def add(
+    name: str,
+    directory: str,
+    description: str | None,
+    timeout: int,
+    model: str | None,
+) -> None:
+    """Add an agent. Auto-generates description from project files if omitted."""
+    try:
+        validate_agent_name(name)
+    except ValueError as e:
+        click.echo(f"Error: {e}")
+        raise SystemExit(1)
+
+    config = load_config()
+    dir_path = Path(directory).resolve()
+
+    if name in config.agents:
+        click.echo(f"Agent '{name}' already exists. Use 'agent-dispatch remove {name}' first.")
+        raise SystemExit(1)
+
+    if description is None:
+        description = auto_describe(dir_path)
+        click.echo(f"Auto-generated description: {description}")
+
+    config.agents[name] = AgentConfig(
+        directory=dir_path,
+        description=description,
+        timeout=timeout,
+        model=model,
+    )
+    save_config(config)
+    click.echo(f"Added agent '{name}' -> {dir_path}")
+
+
+@cli.command()
+@click.argument("name")
+def remove(name: str) -> None:
+    """Remove an agent."""
+    config = load_config()
+    if name not in config.agents:
+        click.echo(f"Agent '{name}' not found.")
+        raise SystemExit(1)
+
+    del config.agents[name]
+    save_config(config)
+    click.echo(f"Removed agent '{name}'.")
+
+
+@cli.command("list")
+def list_agents() -> None:
+    """List configured agents with health status."""
+    config = load_config()
+    if not config.agents:
+        click.echo("No agents configured. Run: agent-dispatch add <name> <directory>")
+        return
+
+    for name, agent in config.agents.items():
+        healthy = agent.directory.is_dir()
+        status = click.style("OK", fg="green") if healthy else click.style("NOT FOUND", fg="red")
+        click.echo(f"  {name} [{status}]")
+        click.echo(f"    dir:  {agent.directory}")
+        click.echo(f"    desc: {agent.description}")
+        click.echo()
+
+
+@cli.command()
+@click.argument("name")
+@click.argument("task", default="What project is this? Describe in one sentence.")
+def test(name: str, task: str) -> None:
+    """Test an agent by dispatching a task."""
+    config = load_config()
+    if name not in config.agents:
+        click.echo(f"Agent '{name}' not found. Run 'agent-dispatch list' to see agents.")
+        raise SystemExit(1)
+
+    agent = config.agents[name]
+    click.echo(f"Dispatching to '{name}' ({agent.directory})...")
+    click.echo(f"Task: {task}")
+    click.echo("---")
+
+    from .runner import dispatch
+
+    result = dispatch(name, task, agent, config.settings)
+
+    if result.success:
+        click.echo(result.result)
+        if result.cost_usd is not None:
+            click.echo(f"\n--- Cost: ${result.cost_usd:.4f} | Turns: {result.num_turns}")
+    else:
+        click.echo(click.style(f"Error: {result.error}", fg="red"))
+        raise SystemExit(1)
+
+
+@cli.command()
+def serve() -> None:
+    """Start the MCP server (stdio transport)."""
+    from .server import main
+
+    main()

agent_dispatch/config.py

@@ -0,0 +1,153 @@
+"""Configuration loading and saving."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+
+import yaml
+
+from .models import DispatchConfig
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CONFIG_DIR = Path.home() / ".config" / "agent-dispatch"
+DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_DIR / "agents.yaml"
+
+
+def config_path() -> Path:
+    """Return config path, respecting AGENT_DISPATCH_CONFIG env var."""
+    return Path(os.environ.get("AGENT_DISPATCH_CONFIG", str(DEFAULT_CONFIG_PATH)))
+
+
+def load_config(path: Path | None = None) -> DispatchConfig:
+    """Load config from YAML file. Returns empty config if file missing."""
+    p = path or config_path()
+    if not p.exists():
+        return DispatchConfig()
+    raw = yaml.safe_load(p.read_text(encoding="utf-8"))
+    if raw is None:
+        return DispatchConfig()
+    return DispatchConfig.model_validate(raw)
+
+
+def save_config(config: DispatchConfig, path: Path | None = None) -> None:
+    """Save config to YAML file."""
+    p = path or config_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    data = config.model_dump(mode="json", exclude_none=True)
+    p.write_text(
+        yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False),
+        encoding="utf-8",
+    )
+
+
+def _collect_mcp_servers(directory: Path) -> list[str]:
+    """Collect MCP server names from all known config locations."""
+    servers: list[str] = []
+    for path in (
+        directory / ".mcp.json",
+        directory / ".claude" / "settings.local.json",
+    ):
+        if path.exists():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                servers.extend(data.get("mcpServers", {}).keys())
+            except (json.JSONDecodeError, KeyError):
+                pass
+    return list(dict.fromkeys(servers))  # deduplicate, preserve order
+
+
+def auto_describe(directory: Path) -> str:
+    """Generate agent description by reading project files.
+
+    Produces a string like:
+      MCP server for cross-project agent delegation | MCP: portainer, postgres | Python, Docker
+    """
+    parts: list[str] = []
+
+    # CLAUDE.md — first meaningful lines (up to 2 sentences)
+    claude_md = directory / "CLAUDE.md"
+    if claude_md.exists():
+        sentences: list[str] = []
+        for line in claude_md.read_text(encoding="utf-8").strip().splitlines()[:40]:
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#") and not stripped.startswith("--"):
+                sentences.append(stripped)
+                if len(sentences) >= 2:
+                    break
+        if sentences:
+            parts.append(" ".join(sentences))
+
+    # README.md — fallback if no CLAUDE.md description
+    if not parts:
+        readme = directory / "README.md"
+        if readme.exists():
+            for line in readme.read_text(encoding="utf-8").strip().splitlines()[:20]:
+                stripped = line.strip()
+                if (
+                    stripped
+                    and not stripped.startswith("#")
+                    and not stripped.startswith("[")
+                    and not stripped.startswith("!")
+                    and len(stripped) > 20
+                ):
+                    parts.append(stripped)
+                    break
+
+    # pyproject.toml — project description
+    pyproject = directory / "pyproject.toml"
+    if pyproject.exists():
+        for line in pyproject.read_text(encoding="utf-8").splitlines():
+            if line.strip().startswith("description"):
+                desc = line.split("=", 1)[1].strip().strip('"').strip("'")
+                if desc:
+                    parts.append(desc)
+                break
+
+    # package.json — project description
+    pkg_json = directory / "package.json"
+    if pkg_json.exists():
+        try:
+            pkg = json.loads(pkg_json.read_text(encoding="utf-8"))
+            if pkg.get("description"):
+                parts.append(pkg["description"])
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    # MCP servers — critical for understanding what tools this agent has
+    servers = _collect_mcp_servers(directory)
+    if servers:
+        parts.append(f"MCP: {', '.join(servers)}")
+
+    # Stack indicators
+    indicators = []
+    if (directory / "Dockerfile").exists():
+        indicators.append("Docker")
+    if (directory / "docker-compose.yaml").exists() or (directory / "docker-compose.yml").exists():
+        indicators.append("Docker Compose")
+    if (directory / "Cargo.toml").exists():
+        indicators.append("Rust")
+    if (directory / "go.mod").exists():
+        indicators.append("Go")
+    if (directory / "requirements.txt").exists() or pyproject.exists():
+        indicators.append("Python")
+    if pkg_json.exists():
+        indicators.append("Node.js")
+    if indicators:
+        parts.append(f"Stack: {', '.join(indicators)}")
+
+    # Database indicators
+    db_indicators = []
+    if (directory / "prisma").is_dir() or (directory / "schema.prisma").exists():
+        db_indicators.append("Prisma")
+    if (directory / "alembic").is_dir() or (directory / "alembic.ini").exists():
+        db_indicators.append("Alembic")
+    if (directory / "migrations").is_dir():
+        db_indicators.append("migrations")
+    if db_indicators:
+        parts.append(f"DB: {', '.join(db_indicators)}")
+
+    return " | ".join(parts) if parts else f"Agent in {directory.name}"

agent_dispatch/models.py

@@ -0,0 +1,84 @@
+"""Data models for agent-dispatch."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field, field_validator
+
+_AGENT_NAME_PATTERN = r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$"
+
+
+class AgentConfig(BaseModel):
+    """Configuration for a single agent."""
+
+    directory: Path
+    description: str = ""
+    timeout: int = 300
+    max_budget_usd: float | None = None
+    model: str | None = None
+    permission_mode: str | None = None
+    allowed_tools: list[str] = Field(default_factory=list)
+    disallowed_tools: list[str] = Field(default_factory=list)
+
+    @field_validator("directory", mode="before")
+    @classmethod
+    def expand_home(cls, v: str | Path) -> Path:
+        return Path(v).expanduser().resolve()
+
+
+class CacheSettings(BaseModel):
+    """Cache configuration."""
+
+    enabled: bool = True
+    ttl: int = Field(default=300, ge=0)  # seconds; 0 effectively disables
+
+    @field_validator("ttl", mode="after")
+    @classmethod
+    def warn_zero_ttl(cls, v: int) -> int:
+        # ttl=0 is valid (entries expire immediately) but likely a mistake.
+        # Let it through — cache.put() will store, cache.get() will evict.
+        return v
+
+
+class Settings(BaseModel):
+    """Global settings for agent-dispatch."""
+
+    default_timeout: int = 300
+    default_max_budget_usd: float | None = None
+    max_dispatch_depth: int = Field(default=3, ge=1)
+    max_concurrency: int = Field(default=5, ge=1)
+    cache: CacheSettings = Field(default_factory=CacheSettings)
+
+
+def validate_agent_name(name: str) -> str:
+    """Validate agent name: alphanumeric, hyphens, underscores, no leading special chars."""
+    import re
+
+    if not re.match(_AGENT_NAME_PATTERN, name):
+        raise ValueError(
+            f"Invalid agent name: {name!r}. "
+            "Use only letters, digits, hyphens, and underscores. "
+            "Must start with a letter or digit."
+        )
+    return name
+
+
+class DispatchConfig(BaseModel):
+    """Top-level config: agents + settings."""
+
+    agents: dict[str, AgentConfig] = Field(default_factory=dict)
+    settings: Settings = Field(default_factory=Settings)
+
+
+class DispatchResult(BaseModel):
+    """Result of a dispatch call."""
+
+    agent: str
+    success: bool
+    result: str
+    session_id: str | None = None
+    cost_usd: float | None = None
+    duration_ms: int | None = None
+    num_turns: int | None = None
+    error: str | None = None