tribunal-kit 1.0.0 → 2.4.2

package/.agent/scripts/swarm_dispatcher.py

@@ -0,0 +1,317 @@
+import argparse
+import json
+import logging
+import os
+import sys
+import uuid
+from pathlib import Path
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')
+
+VALID_WORKER_TYPES = {
+    "research", "generate_code", "review_code", "debug",
+    "plan", "design_schema", "write_docs", "security_audit",
+    "optimize", "test"
+}
+
+VALID_RESULT_STATUSES = {"success", "failure", "escalate"}
+
+MAX_GOAL_LENGTH = 200
+MAX_CONTEXT_LENGTH = 800
+MAX_WORKERS_PER_SWARM = 5
+
+
+def find_agent_dir(start_path: Path) -> Path:
+    current = start_path.resolve()
+    while current != current.parent:
+        agent_dir = current / '.agent'
+        if agent_dir.exists() and agent_dir.is_dir():
+            return agent_dir
+        current = current.parent
+    return None
+
+
+# ─── Legacy mode: validate orchestrator micro-worker payloads ──────────────────
+
+def validate_payload(payload_data: dict, workspace_root: Path, agents_dir: Path) -> bool:
+    if "dispatch_micro_workers" not in payload_data:
+        logging.error("Payload missing required 'dispatch_micro_workers' array.")
+        return False
+
+    workers = payload_data.get("dispatch_micro_workers", [])
+    if not isinstance(workers, list):
+        logging.error("'dispatch_micro_workers' must be a list.")
+        return False
+
+    all_valid = True
+    for i, worker in enumerate(workers):
+        agent_name = worker.get("target_agent")
+        if not agent_name:
+            logging.error(f"Worker {i}: missing 'target_agent'.")
+            all_valid = False
+            continue
+
+        agent_file = agents_dir / f"{agent_name}.md"
+        if not agent_file.exists():
+            logging.error(f"Worker {i}: target_agent '{agent_name}' not found at {agent_file}.")
+            all_valid = False
+
+        files_attached = worker.get("files_attached", [])
+        if not isinstance(files_attached, list):
+            logging.error(f"Worker {i}: 'files_attached' must be a list.")
+            all_valid = False
+            continue
+
+        for f in files_attached:
+            file_path = workspace_root / f
+            if not file_path.exists():
+                logging.warning(f"Worker {i}: attached file '{f}' does not exist (might be a new file to create).")
+
+    return all_valid
+
+
+def build_worker_prompts(payload_data: dict, workspace_root: Path) -> list:
+    prompts = []
+    workers = payload_data.get("dispatch_micro_workers", [])
+    for worker in workers:
+        agent = worker.get("target_agent")
+        ctx = worker.get("context_summary", "")
+        task = worker.get("task_description", "")
+        files = worker.get("files_attached", [])
+
+        prompt = f"--- MICRO-WORKER DISPATCH ---\n"
+        prompt += f"Agent: {agent}\n"
+        prompt += f"Context: {ctx}\n"
+        prompt += f"Task: {task}\n"
+        prompt += f"Attached Files: {', '.join(files) if files else 'None'}\n"
+        prompt += "-----------------------------"
+        prompts.append(prompt)
+    return prompts
+
+
+# ─── Swarm mode: validate WorkerRequest / WorkerResult payloads ───────────────
+
+def validate_worker_request(req: dict, index: int, agents_dir: Path) -> list[str]:
+    """Validate a single WorkerRequest object. Returns a list of error strings."""
+    errors = []
+
+    # task_id
+    task_id = req.get("task_id", "")
+    if not task_id or not isinstance(task_id, str):
+        errors.append(f"WorkerRequest[{index}]: 'task_id' must be a non-empty string.")
+
+    # type
+    req_type = req.get("type", "")
+    if req_type not in VALID_WORKER_TYPES:
+        errors.append(
+            f"WorkerRequest[{index}]: 'type' must be one of {sorted(VALID_WORKER_TYPES)}, got '{req_type}'."
+        )
+
+    # agent
+    agent = req.get("agent", "")
+    if not agent or not isinstance(agent, str):
+        errors.append(f"WorkerRequest[{index}]: 'agent' must be a non-empty string.")
+    else:
+        agent_file = agents_dir / f"{agent}.md"
+        if not agent_file.exists():
+            errors.append(
+                f"WorkerRequest[{index}]: agent '{agent}' not found at {agent_file}. "
+                f"Only agents that exist in .agent/agents/ are valid."
+            )
+
+    # goal
+    goal = req.get("goal", "")
+    if not goal or not isinstance(goal, str):
+        errors.append(f"WorkerRequest[{index}]: 'goal' must be a non-empty string.")
+    elif len(goal) > MAX_GOAL_LENGTH:
+        errors.append(
+            f"WorkerRequest[{index}]: 'goal' exceeds {MAX_GOAL_LENGTH} characters ({len(goal)} chars). "
+            f"Keep it to a single, focused sentence."
+        )
+
+    # context
+    context = req.get("context", "")
+    if not context or not isinstance(context, str):
+        errors.append(f"WorkerRequest[{index}]: 'context' must be a non-empty string.")
+    elif len(context) > MAX_CONTEXT_LENGTH:
+        errors.append(
+            f"WorkerRequest[{index}]: 'context' exceeds {MAX_CONTEXT_LENGTH} characters ({len(context)} chars). "
+            f"Trim to minimal required context only."
+        )
+
+    # max_retries
+    max_retries = req.get("max_retries")
+    if not isinstance(max_retries, int) or not (1 <= max_retries <= 3):
+        errors.append(
+            f"WorkerRequest[{index}]: 'max_retries' must be an integer between 1 and 3, got '{max_retries}'."
+        )
+
+    return errors
+
+
+def validate_worker_result(res: dict, index: int) -> list[str]:
+    """Validate a single WorkerResult object. Returns a list of error strings."""
+    errors = []
+
+    # task_id
+    task_id = res.get("task_id", "")
+    if not task_id or not isinstance(task_id, str):
+        errors.append(f"WorkerResult[{index}]: 'task_id' must be a non-empty string.")
+
+    # agent
+    agent = res.get("agent", "")
+    if not agent or not isinstance(agent, str):
+        errors.append(f"WorkerResult[{index}]: 'agent' must be a non-empty string.")
+
+    # status
+    status = res.get("status", "")
+    if status not in VALID_RESULT_STATUSES:
+        errors.append(
+            f"WorkerResult[{index}]: 'status' must be one of {sorted(VALID_RESULT_STATUSES)}, got '{status}'."
+        )
+
+    # output / error rules
+    output = res.get("output", "")
+    error = res.get("error", "")
+    if status == "success" and not output:
+        errors.append(f"WorkerResult[{index}]: 'output' is required when status is 'success'.")
+    if status in ("failure", "escalate") and not error:
+        errors.append(
+            f"WorkerResult[{index}]: 'error' is required when status is '{status}'. "
+            f"Be specific — 'Something went wrong' is not acceptable."
+        )
+
+    # attempts
+    attempts = res.get("attempts")
+    if not isinstance(attempts, int) or attempts < 1:
+        errors.append(f"WorkerResult[{index}]: 'attempts' must be an integer >= 1, got '{attempts}'.")
+
+    return errors
+
+
+def validate_swarm_payload(payload_data, agents_dir: Path) -> bool:
+    """
+    Validate a Swarm payload. Accepts either:
+    - A single WorkerRequest object (dict with 'task_id', 'type', 'agent', ...)
+    - A single WorkerResult object (dict with 'task_id', 'agent', 'status', ...)
+    - A list of WorkerRequests
+    - A list of WorkerResults
+    - An object with a top-level 'workers' array of WorkerRequests
+    """
+    # Normalise to a list
+    if isinstance(payload_data, dict):
+        if "workers" in payload_data:
+            items = payload_data["workers"]
+        else:
+            items = [payload_data]
+    elif isinstance(payload_data, list):
+        items = payload_data
+    else:
+        logging.error("Swarm payload must be a JSON object or array.")
+        return False
+
+    if len(items) > MAX_WORKERS_PER_SWARM:
+        logging.error(
+            f"Swarm payload contains {len(items)} workers, "
+            f"exceeding the maximum of {MAX_WORKERS_PER_SWARM}."
+        )
+        return False
+
+    all_errors = []
+    for i, item in enumerate(items):
+        if not isinstance(item, dict):
+            all_errors.append(f"Item[{i}]: must be a JSON object.")
+            continue
+
+        # Detect whether this is a WorkerRequest or WorkerResult by key presence
+        if "status" in item and "output" in item:
+            # Looks like a WorkerResult
+            errors = validate_worker_result(item, i)
+        else:
+            # Treat as WorkerRequest
+            errors = validate_worker_request(item, i, agents_dir)
+
+        all_errors.extend(errors)
+
+    if all_errors:
+        for err in all_errors:
+            logging.error(err)
+        return False
+
+    return True
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description=(
+            "Validate Orchestrator micro-worker payloads (legacy) "
+            "and Swarm WorkerRequest/WorkerResult payloads (swarm mode)."
+        )
+    )
+    parser.add_argument("--payload", type=str, help="JSON string of the payload", required=False)
+    parser.add_argument("--file", type=str, help="Path to a JSON file containing the payload", required=False)
+    parser.add_argument("--workspace", type=str, default=".", help="Workspace root directory")
+    parser.add_argument(
+        "--mode",
+        type=str,
+        choices=["legacy", "swarm"],
+        default="legacy",
+        help=(
+            "Validation mode. "
+            "'legacy': validate orchestrator dispatch_micro_workers payload (default). "
+            "'swarm': validate WorkerRequest or WorkerResult JSON."
+        )
+    )
+
+    args = parser.parse_args()
+
+    if not args.payload and not args.file:
+        logging.error("Must provide either --payload or --file")
+        sys.exit(1)
+
+    workspace_root = Path(args.workspace).resolve()
+    agent_dir = find_agent_dir(workspace_root)
+
+    if not agent_dir:
+        logging.error(f"Could not find .agent directory starting from {workspace_root}")
+        sys.exit(1)
+
+    agents_dir = agent_dir / "agents"
+    if not agents_dir.exists():
+        logging.error(f"Could not find 'agents' directory inside {agent_dir}")
+        sys.exit(1)
+
+    try:
+        if args.file:
+            with open(args.file, 'r', encoding='utf-8') as f:
+                payload_data = json.load(f)
+        else:
+            payload_data = json.loads(args.payload)
+    except Exception as e:
+        logging.error(f"Failed to parse payload as JSON: {e}")
+        sys.exit(1)
+
+    if args.mode == "swarm":
+        if not validate_swarm_payload(payload_data, agents_dir):
+            logging.error("Swarm payload validation failed.")
+            sys.exit(1)
+        logging.info("Swarm payload validation successful.")
+    else:
+        # Legacy mode
+        if not validate_payload(payload_data, workspace_root, agents_dir):
+            logging.error("Payload validation failed.")
+            sys.exit(1)
+
+        logging.info("Payload validation successful.")
+        prompts = build_worker_prompts(payload_data, workspace_root)
+
+        for i, p in enumerate(prompts):
+            print(f"\n[Worker {i+1} Ready]")
+            print(p)
+
+
+if __name__ == "__main__":
+    main()

package/.agent/scripts/test_runner.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+test_runner.py — Standalone test runner for the Tribunal Agent Kit.
+
+Detects and runs the project's test framework:
+  - npm test (Jest / Vitest / Mocha)
+  - pytest (Python)
+  - go test (Go)
+
+Usage:
+  python .agent/scripts/test_runner.py .
+  python .agent/scripts/test_runner.py . --coverage
+  python .agent/scripts/test_runner.py . --watch
+  python .agent/scripts/test_runner.py . --file src/utils.test.ts
+"""
+
+import os
+import sys
+import subprocess
+import argparse
+from pathlib import Path
+
+RED = "\033[91m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+BLUE = "\033[94m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+
+def header(title: str) -> None:
+    print(f"\n{BOLD}{BLUE}━━━ {title} ━━━{RESET}")
+
+
+def ok(msg: str) -> None:
+    print(f"  {GREEN}✅ {msg}{RESET}")
+
+
+def fail(msg: str) -> None:
+    print(f"  {RED}❌ {msg}{RESET}")
+
+
+def skip(msg: str) -> None:
+    print(f"  {YELLOW}⏭️  {msg}{RESET}")
+
+
+def run_tests(label: str, cmd: list[str], cwd: str) -> bool:
+    """Run a test command, streaming output in real-time."""
+    try:
+        result = subprocess.run(
+            cmd, cwd=cwd, capture_output=True, text=True, timeout=300
+        )
+        output = (result.stdout + result.stderr).strip()
+        if output:
+            for line in output.split("\n"):
+                print(f"    {line}")
+
+        if result.returncode == 0:
+            ok(f"{label} — all tests passed")
+            return True
+        fail(f"{label} — test failures detected")
+        return False
+    except FileNotFoundError:
+        skip(f"{label} — tool not installed")
+        return True
+    except subprocess.TimeoutExpired:
+        fail(f"{label} — timed out after 300s")
+        return False
+
+
+def detect_test_framework(project_root: str) -> str | None:
+    """Detect the primary test framework from project files."""
+    root = Path(project_root)
+
+    # Node.js test frameworks
+    pkg_json = root / "package.json"
+    if pkg_json.exists():
+        try:
+            import json
+            with open(pkg_json) as f:
+                pkg = json.load(f)
+            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+            scripts = pkg.get("scripts", {})
+
+            if "vitest" in deps:
+                return "vitest"
+            if "jest" in deps:
+                return "jest"
+            if "mocha" in deps:
+                return "mocha"
+            if "test" in scripts:
+                return "npm-test"
+        except Exception:
+            if "test" in str(pkg_json.read_text()):
+                return "npm-test"
+
+    # Python
+    if (root / "pytest.ini").exists() or (root / "pyproject.toml").exists() or (root / "conftest.py").exists():
+        return "pytest"
+
+    # Go
+    go_files = list(root.glob("**/*_test.go"))
+    if go_files:
+        return "go"
+
+    return None
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Tribunal test runner — detects and runs the project's test framework"
+    )
+    parser.add_argument("path", help="Project root directory")
+    parser.add_argument("--coverage", action="store_true", help="Run tests with coverage reporting")
+    parser.add_argument("--watch", action="store_true", help="Run tests in watch mode")
+    parser.add_argument("--file", help="Run tests for a specific file only")
+    args = parser.parse_args()
+
+    project_root = os.path.abspath(args.path)
+    if not os.path.isdir(project_root):
+        fail(f"Directory not found: {project_root}")
+        sys.exit(1)
+
+    print(f"{BOLD}Tribunal — test_runner.py{RESET}")
+    print(f"Project: {project_root}")
+
+    framework = detect_test_framework(project_root)
+    if not framework:
+        skip("No test framework detected in this project")
+        sys.exit(0)
+
+    header(f"Running tests ({framework})")
+
+    cmd: list[str] = []
+    passed = True
+
+    if framework in ("vitest", "jest", "mocha", "npm-test"):
+        if framework == "vitest":
+            cmd = ["npx", "vitest", "run"]
+            if args.coverage:
+                cmd.append("--coverage")
+            if args.watch:
+                cmd = ["npx", "vitest"]  # watch is vitest default
+            if args.file:
+                cmd.append(args.file)
+        elif framework == "jest":
+            cmd = ["npx", "jest"]
+            if args.coverage:
+                cmd.append("--coverage")
+            if args.watch:
+                cmd.append("--watch")
+            if args.file:
+                cmd.append(args.file)
+        else:
+            cmd = ["npm", "test", "--", "--passWithNoTests"]
+            if args.coverage:
+                cmd.append("--coverage")
+            if args.file:
+                cmd.append(args.file)
+        passed = run_tests(framework, cmd, project_root)
+
+    elif framework == "pytest":
+        cmd = ["python", "-m", "pytest", "-v"]
+        if args.coverage:
+            cmd.extend(["--cov", "--cov-report=term-missing"])
+        if args.watch:
+            cmd = ["python", "-m", "pytest-watch", "--", "-v"]  # pytest-watch
+
+        if args.file:
+            cmd.append(args.file)
+        passed = run_tests("pytest", cmd, project_root)
+
+    elif framework == "go":
+        cmd = ["go", "test", "./...", "-v"]
+        if args.coverage:
+            cmd.append("-cover")
+        if args.file:
+            cmd = ["go", "test", "-v", "-run", args.file]
+        passed = run_tests("go test", cmd, project_root)
+
+    # Summary
+    print(f"\n{BOLD}━━━ Test Summary ━━━{RESET}")
+    if passed:
+        ok(f"Tests passed ({framework})")
+    else:
+        fail(f"Tests failed ({framework})")
+
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/.agent/scripts/test_swarm_dispatcher.py

@@ -0,0 +1,163 @@
+import pytest
+from pathlib import Path
+
+# Adjust the path so we can import swarm_dispatcher directly
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from swarm_dispatcher import find_agent_dir, validate_payload, build_worker_prompts
+
+
+def test_find_agent_dir_found(tmp_path):
+    # Setup: Create an .agent directory and a deep subdirectory
+    agent_dir = tmp_path / ".agent"
+    agent_dir.mkdir()
+    sub_dir = tmp_path / "src" / "deep" / "folder"
+    sub_dir.mkdir(parents=True)
+    
+    # Act & Assert
+    result = find_agent_dir(sub_dir)
+    assert result is not None
+    assert result.resolve() == agent_dir.resolve()
+
+def test_find_agent_dir_not_found(tmp_path):
+    # Setup: Directory structure without '.agent'
+    sub_dir = tmp_path / "src" / "deep"
+    sub_dir.mkdir(parents=True)
+    
+    # Act & Assert
+    assert find_agent_dir(sub_dir) is None
+
+def test_validate_payload_valid(tmp_path):
+    # Setup
+    agents_dir = tmp_path / "agents"
+    agents_dir.mkdir()
+    agent_file = agents_dir / "test_agent.md"
+    agent_file.touch()
+    
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    file_attached = workspace / "file1.txt"
+    file_attached.touch()
+
+    payload = {
+        "dispatch_micro_workers": [
+            {
+                "target_agent": "test_agent",
+                "files_attached": ["file1.txt"]
+            }
+        ]
+    }
+    
+    # Act & Assert
+    assert validate_payload(payload, workspace, agents_dir) is True
+
+def test_validate_payload_missing_workers(tmp_path):
+    # Act & Assert
+    assert validate_payload({}, tmp_path, tmp_path) is False
+
+def test_validate_payload_not_list(tmp_path):
+    # Act & Assert
+    assert validate_payload({"dispatch_micro_workers": "str"}, tmp_path, tmp_path) is False
+
+def test_validate_payload_missing_target_agent(tmp_path):
+    # Setup
+    payload = {
+        "dispatch_micro_workers": [
+            {
+                "files_attached": []
+            }
+        ]
+    }
+    
+    # Act & Assert
+    assert validate_payload(payload, tmp_path, tmp_path) is False
+
+def test_validate_payload_agent_not_found(tmp_path):
+    # Setup
+    agents_dir = tmp_path / "agents"
+    agents_dir.mkdir()
+    
+    payload = {
+        "dispatch_micro_workers": [
+            {
+                "target_agent": "missing_agent"
+            }
+        ]
+    }
+    
+    # Act & Assert
+    assert validate_payload(payload, tmp_path, agents_dir) is False
+
+def test_validate_payload_files_not_a_list(tmp_path):
+    agents_dir = tmp_path / "agents"
+    agents_dir.mkdir()
+    (agents_dir / "test_agent.md").touch()
+    
+    payload = {
+        "dispatch_micro_workers": [
+            {
+                "target_agent": "test_agent",
+                "files_attached": "a single file string"
+            }
+        ]
+    }
+    
+    assert validate_payload(payload, tmp_path, agents_dir) is False
+
+def test_validate_payload_files_missing_warning(tmp_path, caplog):
+    # Tests that the validation still passes if files are missing,
+    # but that a warning is logged.
+    agents_dir = tmp_path / "agents"
+    agents_dir.mkdir()
+    (agents_dir / "test_agent.md").touch()
+    
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+
+    payload = {
+        "dispatch_micro_workers": [
+            {
+                "target_agent": "test_agent",
+                "files_attached": ["nonexistent.txt"]
+            }
+        ]
+    }
+    
+    assert validate_payload(payload, workspace, agents_dir) is True
+    assert "attached file 'nonexistent.txt' does not exist" in caplog.text
+
+def test_build_worker_prompts():
+    payload = {
+        "dispatch_micro_workers": [
+            {
+                "target_agent": "worker1",
+                "context_summary": "Initial context value",
+                "task_description": "First task to do",
+                "files_attached": ["main.py", "utils.py"]
+            },
+            {
+                "target_agent": "worker2",
+                "context_summary": "Another context",
+                "task_description": "Second task",
+                "files_attached": []
+            }
+        ]
+    }
+    
+    prompts = build_worker_prompts(payload, Path("."))
+    
+    assert len(prompts) == 2
+    
+    # Check first prompt
+    assert "Agent: worker1" in prompts[0]
+    assert "Context: Initial context value" in prompts[0]
+    assert "Task: First task to do" in prompts[0]
+    assert "Attached Files: main.py, utils.py" in prompts[0]
+    
+    # Check second prompt
+    assert "Agent: worker2" in prompts[1]
+    assert "Context: Another context" in prompts[1]
+    assert "Task: Second task" in prompts[1]
+    assert "Attached Files: None" in prompts[1]