maestro-agents 0.1.0__tar.gz

maestro_agents-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Type checking
+.mypy_cache/
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+uv.lock
+
+# Project
+*.db
+*.sqlite3
+.maestro/
+src/api/
+
+# env
+.env

maestro_agents-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: maestro-agents
+Version: 0.1.0
+Summary: Role-specific LLM agents with SSOT integration
+Requires-Python: >=3.12
+Requires-Dist: litellm>=1.50
+Requires-Dist: maestro-harness
+Requires-Dist: maestro-ssot
+Requires-Dist: pydantic-ai>=0.5
+Requires-Dist: pydantic>=2.10
+Requires-Dist: rich>=13.0

maestro_agents-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "maestro-agents"
+version = "0.1.0"
+description = "Role-specific LLM agents with SSOT integration"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.10",
+    "pydantic-ai>=0.5",
+    "litellm>=1.50",
+    "rich>=13.0",
+    "maestro-ssot",
+    "maestro-harness",
+]
+
+[tool.uv.sources]
+maestro-ssot = { workspace = true }
+maestro-harness = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maestro_agents"]

maestro_agents-0.1.0/src/maestro_agents/__init__.py

@@ -0,0 +1,8 @@
+"""MAESTRO role agents package."""
+
+from __future__ import annotations
+
+from .animation import ThinkingAnimation
+from .base import AgentResult, MaestroAgent
+
+__all__ = ["AgentResult", "MaestroAgent", "ThinkingAnimation"]

maestro_agents-0.1.0/src/maestro_agents/animation.py

@@ -0,0 +1,79 @@
+"""Rich-based thinking animation and typewriter output for agent execution."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from rich.live import Live
+
+
+class ThinkingAnimation:
+    """Display a thinking spinner during LLM calls, then typewriter output.
+
+    Example::
+        anim = ThinkingAnimation("planner-1 planning")
+        anim.start()
+        # ... await LLM call ...
+        anim.stop()
+        anim.typewrite(result_text, prefix="[cyan]planner-1[/] ")
+    """
+
+    def __init__(self, label: str = "thinking", console: Console | None = None) -> None:
+        self.label = label
+        self._console = console
+        self._live: Live | None = None
+
+    def _get_console(self) -> Console:
+        if self._console is not None:
+            return self._console
+        from rich.console import Console
+
+        return Console()
+
+    def start(self) -> None:
+        """Start the thinking spinner."""
+        from rich.live import Live
+        from rich.spinner import Spinner
+
+        spinner = Spinner("dots", text=f"[dim]{self.label}[/]")
+        self._live = Live(
+            spinner, refresh_per_second=8, transient=True, console=self._get_console()
+        )
+        self._live.start()
+
+    def stop(self) -> None:
+        """Stop the spinner."""
+        if self._live is not None:
+            self._live.stop()
+            self._live = None
+
+    def typewrite(
+        self,
+        text: str,
+        prefix: str = "",
+        delay: float = 0.008,
+        max_chars: int = 2000,
+    ) -> None:
+        """Print text with a typewriter effect.
+
+        For long text (>max_chars), speeds up to avoid excessive wait time.
+        """
+        console = self._get_console()
+        text = text.strip()
+        if not text:
+            return
+
+        # Speed up for very long text
+        if len(text) > max_chars:
+            delay = max(0.001, delay * max_chars / len(text))
+
+        if prefix:
+            console.print(prefix, end="")
+
+        for char in text:
+            console.print(char, end="")
+            time.sleep(delay)
+        console.print()  # newline

maestro_agents-0.1.0/src/maestro_agents/backend.py

@@ -0,0 +1,33 @@
+"""BackendAgent: implements backend code consuming contracts from SSOT."""
+
+from __future__ import annotations
+
+from maestro_agents.base import MaestroAgent
+
+
+class BackendAgent(MaestroAgent):
+    """Implements backend modules by reading contracts and writing code.
+
+    Uses SSOT tools to:
+    1. Claim a requirement assigned to the backend
+    2. Read the relevant contracts
+    3. Write implementation code via the harness sandbox
+    4. Update requirement status to DONE when complete
+    """
+
+    role = "backend"
+
+    def system_prompt(self) -> str:
+        return (
+            "You are the Backend Agent in the MAESTRO multi-agent system. "
+            "Your job is to implement backend code based on requirements and "
+            "API contracts from the SSOT. "
+            "Read the assigned requirement and its contracts, then write "
+            "clean, well-structured Python code to actual files. "
+            "You have file_read, file_write, and shell_exec tools to interact "
+            "with the codebase. Use file_write to create/modify source files, "
+            "shell_exec to run tests and verify your implementation. "
+            "Do NOT use 'cd' in shell commands — the sandbox cwd is already "
+            "the project root. Use the SSOT tools to read contracts and requirements, "
+            "and update the requirement status when done."
+        )

maestro_agents-0.1.0/src/maestro_agents/base.py

@@ -0,0 +1,168 @@
+"""MaestroAgent base class wrapping PydanticAI with SSOT + Harness injection."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+from pydantic_ai import Agent
+from pydantic_ai.settings import ModelSettings
+
+from maestro_harness.harness import Harness
+from maestro_ssot.hub import SSOTHub
+
+from .animation import ThinkingAnimation
+from .deps import AgentDeps
+from .permissions import AgentPermissions
+from .tools import register_tools
+
+if TYPE_CHECKING:
+    from pydantic_ai import AgentEventStream
+
+
+class AgentResult(BaseModel):
+    """Result of a single agent execution."""
+
+    output: str
+    success: bool = True
+    error: str | None = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+class MaestroAgent:
+    """Base class for all MAESTRO role agents.
+
+    Wraps a PydanticAI Agent with SSOT and Harness dependencies.
+    Subclasses override ``system_prompt`` and ``role`` to specialize behavior.
+    """
+
+    role: str = "generic"
+
+    def __init__(
+        self,
+        agent_id: str,
+        hub: SSOTHub,
+        harness: Harness,
+        model: str | object = "test",
+        permissions: AgentPermissions | None = None,
+        thinking: bool | None = None,
+    ) -> None:
+        self.agent_id = agent_id
+        self.hub = hub
+        self.harness = harness
+
+        deps = AgentDeps(
+            hub=hub,
+            harness=harness,
+            agent_id=agent_id,
+            role=self.role,
+        )
+
+        model_settings: ModelSettings | None = None
+        if thinking is not None:
+            model_settings = ModelSettings(thinking=thinking)
+
+        prompt = self.system_prompt() + "\n\n" + self._policy_context()
+        self._agent = Agent(
+            model,  # type: ignore[arg-type]
+            deps_type=AgentDeps,
+            output_type=str,
+            system_prompt=prompt,
+            model_settings=model_settings,
+        )
+        register_tools(self._agent, permissions)
+        self._deps = deps
+
+    def _policy_context(self) -> str:
+        """Return a formatted description of the agent's Harness policy."""
+        lines: list[str] = []
+        policy = self.harness.get_agent_policy(self.agent_id)
+        if policy and policy.filesystem and policy.filesystem.allow:
+            lines.append(f"Allowed file paths: {', '.join(policy.filesystem.allow)}")
+        if policy and policy.filesystem and policy.filesystem.deny:
+            lines.append(f"Denied file paths: {', '.join(policy.filesystem.deny)}")
+        if policy and policy.commands and policy.commands.allow:
+            lines.append(f"Allowed shell commands: {', '.join(policy.commands.allow)}")
+        if policy and policy.commands and policy.commands.deny:
+            lines.append(f"Denied shell commands: {', '.join(policy.commands.deny)}")
+        return "\n".join(lines)
+
+    def system_prompt(self) -> str:
+        return "You are a MAESTRO software engineering agent."
+
+    async def run(
+        self,
+        prompt: str,
+        model: str | object | None = None,
+        animation: ThinkingAnimation | None = None,
+        timeout: float | None = None,
+    ) -> AgentResult:
+        """Execute the agent with optional thinking animation and timeout."""
+        if animation is not None:
+            animation.start()
+        try:
+            run_kwargs: dict[str, object] = {}
+            if model is not None:
+                run_kwargs["model"] = model
+
+            coro = self._agent.run(
+                prompt, deps=self._deps, **run_kwargs  # type: ignore[call-overload]
+            )
+            if timeout is not None and timeout > 0:
+                coro = asyncio.wait_for(coro, timeout=timeout)
+            result = await coro
+            output = str(result.output)
+
+            # Extract token usage if available
+            input_tokens = 0
+            output_tokens = 0
+            try:
+                usage = result.usage
+                if usage is not None:
+                    input_tokens = getattr(usage, "request_tokens", 0) or 0
+                    output_tokens = getattr(usage, "response_tokens", 0) or 0
+            except Exception:
+                pass
+
+            if animation is not None:
+                animation.stop()
+                animation.typewrite(output, prefix=f"[cyan]{self.agent_id}[/] ")
+
+            return AgentResult(
+                output=output,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+            )
+        except TimeoutError:
+            if animation is not None:
+                animation.stop()
+            return AgentResult(
+                output="",
+                success=False,
+                error=f"Agent timed out after {timeout}s",
+            )
+        except Exception as e:
+            if animation is not None:
+                animation.stop()
+            return AgentResult(output="", success=False, error=str(e))
+
+    def run_stream(
+        self,
+        prompt: str,
+        model: str | object | None = None,
+    ) -> AgentEventStream[Any] | None:
+        """Return an event stream for real-time monitoring.
+
+        Returns ``None`` if the underlying model does not support streaming
+        (e.g. TestModel).
+        """
+        run_kwargs: dict[str, object] = {"deps": self._deps}
+        if model is not None:
+            run_kwargs["model"] = model
+        try:
+            return self._agent.run_stream_events(prompt, **run_kwargs)  # type: ignore[call-overload, no-any-return]
+        except Exception:
+            # TestModel and some mock environments don't support streaming
+            return None

maestro_agents-0.1.0/src/maestro_agents/contract_validator.py

@@ -0,0 +1,94 @@
+"""Non-LLM contract validator: rule engine for consumer-producer consistency."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from maestro_ssot.hub import SSOTHub
+from maestro_ssot.models import ContractStatus
+
+
+@dataclass
+class Violation:
+    contract_id: str
+    message: str
+    severity: str = "error"  # error | warning
+
+
+@dataclass
+class ValidationResult:
+    valid: bool
+    violations: list[Violation] = field(default_factory=list)
+
+
+def validate_contracts(hub: SSOTHub) -> ValidationResult:
+    """Check all contracts for consistency violations.
+
+    Rules:
+    1. Stable/Deprecated contracts must have a non-empty interface_schema.
+    2. Consumers of STABLE contracts must not reference DRAFT contracts.
+    3. Contract version should be >= 1.
+    4. All listed consumers should have known activity.
+    """
+    violations: list[Violation] = []
+    contracts = hub._persistence.list_contracts()
+
+    for contract in contracts:
+        # Rule 1: Stable/Deprecated contracts must have interface schema
+        if (
+            contract.status in (ContractStatus.STABLE, ContractStatus.DEPRECATED)
+            and not contract.interface_schema
+        ):
+            violations.append(
+                Violation(
+                    contract_id=contract.id,
+                    message=f"Contract '{contract.name}' is {contract.status.value} "
+                    f"but has empty interface_schema",
+                    severity="error",
+                )
+            )
+
+        # Rule 2: Check consumer references
+        for consumer in contract.consumers:
+            consumer_known = any(c.owner == consumer for c in contracts)
+            if not consumer_known:
+                log_entries = hub.query_log(agent_id=consumer, limit=1)
+                if not log_entries:
+                    violations.append(
+                        Violation(
+                            contract_id=contract.id,
+                            message=f"Consumer '{consumer}' of contract '{contract.name}' "
+                            f"has no known activity",
+                            severity="warning",
+                        )
+                    )
+
+        # Rule 3: Version check
+        if contract.version < 1:
+            violations.append(
+                Violation(
+                    contract_id=contract.id,
+                    message=f"Contract '{contract.name}' has invalid version {contract.version}",
+                    severity="error",
+                )
+            )
+
+        # Rule 4: DRAFT contracts should not have STABLE consumers
+        if contract.status == ContractStatus.DRAFT:
+            for other in contracts:
+                if (
+                    other.id != contract.id
+                    and contract.id in other.consumers
+                    and other.status == ContractStatus.STABLE
+                ):
+                    violations.append(
+                        Violation(
+                            contract_id=other.id,
+                            message=f"STABLE contract '{other.name}' depends on "
+                            f"DRAFT contract '{contract.name}'",
+                            severity="error",
+                        )
+                    )
+
+    errors = [v for v in violations if v.severity == "error"]
+    return ValidationResult(valid=len(errors) == 0, violations=violations)

maestro_agents-0.1.0/src/maestro_agents/deps.py

@@ -0,0 +1,17 @@
+"""Agent dependency types shared between base and tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from maestro_harness.harness import Harness
+from maestro_ssot.hub import SSOTHub
+
+
+@dataclass
+class AgentDeps:
+    hub: SSOTHub
+    harness: Harness
+    agent_id: str
+    role: str
+    memory: dict[str, str] = field(default_factory=dict)

maestro_agents-0.1.0/src/maestro_agents/frontend.py

@@ -0,0 +1,33 @@
+"""FrontendAgent: implements UI components consuming API contracts from SSOT."""
+
+from __future__ import annotations
+
+from maestro_agents.base import MaestroAgent
+
+
+class FrontendAgent(MaestroAgent):
+    """Implements frontend modules by reading contracts and writing client code.
+
+    Uses SSOT tools to:
+    1. Claim a requirement assigned to the frontend
+    2. Read the relevant API contracts
+    3. Write implementation code (React, HTML, CSS, etc.) via the harness sandbox
+    4. Update requirement status to DONE when complete
+    """
+
+    role = "frontend"
+
+    def system_prompt(self) -> str:
+        return (
+            "You are the Frontend Agent in the MAESTRO multi-agent system. "
+            "Your job is to implement frontend code based on requirements and "
+            "API contracts from the SSOT. "
+            "Read the assigned requirement and its contracts, then write "
+            "clean, well-structured client-side code (React, HTML, CSS, JavaScript) "
+            "to actual files. You have file_read, file_write, and shell_exec tools "
+            "to interact with the codebase. Use file_write to create/modify source files, "
+            "shell_exec to run build/lint commands and verify your implementation. "
+            "Do NOT use 'cd' in shell commands — the sandbox cwd is already "
+            "the project root. Use the SSOT tools to read contracts and requirements, "
+            "and update the requirement status when done."
+        )

maestro_agents-0.1.0/src/maestro_agents/permissions.py

@@ -0,0 +1,24 @@
+"""Agent permission model for SSOT tool access control."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class AgentPermissions(BaseModel):
+    """SSOT permissions for an agent — controls which tools are registered.
+
+    All permissions default to True for backward compatibility.
+    Set individual fields to False to restrict an agent's capabilities.
+    """
+
+    read_requirements: bool = True
+    write_requirements: bool = True
+    read_contracts: bool = True
+    write_contracts: bool = True
+    read_memory: bool = True
+    write_memory: bool = True
+    read_log: bool = True
+    read_files: bool = True
+    write_files: bool = True
+    execute_shell: bool = True

maestro_agents-0.1.0/src/maestro_agents/planning.py

@@ -0,0 +1,40 @@
+"""PlanningAgent: decomposes requirements into a structured task tree."""
+
+from __future__ import annotations
+
+from maestro_agents.base import MaestroAgent
+
+
+class PlanningAgent(MaestroAgent):
+    """Decomposes high-level requirements into sub-tasks and registers contracts.
+
+    Uses SSOT tools to:
+    1. Read the root requirement
+    2. Break it into sub-requirements with dependencies
+    3. Register interface contracts between modules
+    """
+
+    role = "planner"
+
+    def system_prompt(self) -> str:
+        return (
+            "You are the Planning Agent in the MAESTRO multi-agent system. "
+            "Your job is to decompose a high-level software requirement into "
+            "a tree of sub-requirements, each with clear acceptance criteria "
+            "and dependencies. You should also register API contracts between "
+            "modules that need to communicate. "
+            "Use the SSOT tools to add requirements and register contracts. "
+            "Be specific: each sub-requirement should be small enough for a "
+            "single agent to implement in one iteration.\n\n"
+            "CRITICAL RULES:\n"
+            "1. Every sub-requirement MUST specify a valid parent_id. "
+            "   Pass the root requirement ID as parent_id for all sub-tasks.\n"
+            "2. Do NOT create duplicate tasks. Check existing requirements first.\n"
+            "3. Limit decomposition to 5-7 sub-tasks maximum. "
+            "   If the requirement is simple, create fewer tasks or even just one.\n"
+            "4. Dependencies must reference task IDs that you have already created "
+            "   in this same planning session. Do NOT reference tasks from previous sessions.\n"
+            "5. Only register contracts for actual API boundaries between modules.\n"
+            "6. Do NOT assign tasks to specific agents yourself — "
+            "   the scheduler will handle assignment."
+        )

maestro_agents-0.1.0/src/maestro_agents/review.py

@@ -0,0 +1,31 @@
+"""ReviewAgent: checks contract compliance, code quality, and security issues."""
+
+from __future__ import annotations
+
+from maestro_agents.base import MaestroAgent
+
+
+class ReviewAgent(MaestroAgent):
+    """Validates code and contract quality before COMMIT.
+
+    Uses SSOT tools to:
+    1. Read all contracts and their consumers
+    2. Read recent execution logs and code changes
+    3. Check for contract violations, security issues, and code smells
+    4. Annotate the execution log with review findings
+    """
+
+    role = "review"
+
+    def system_prompt(self) -> str:
+        return (
+            "You are the Review Agent in the MAESTRO multi-agent system. "
+            "Your job is to review code and contracts for quality, security, "
+            "and compliance before the system commits an epoch. "
+            "You have file_read and shell_exec tools. Use file_read to inspect "
+            "source files, and shell_exec to run linters (ruff, mypy) and static "
+            "analysis. Do NOT use 'cd' in shell commands — the sandbox cwd is already "
+            "the project root. Read the contracts and execution log from the SSOT. "
+            "Report any issues you find and suggest fixes. "
+            "Use the SSOT tools to read state and annotate the execution log."
+        )

maestro_agents-0.1.0/src/maestro_agents/test_agent.py

@@ -0,0 +1,39 @@
+"""TestAgent: writes and runs tests, reports coverage."""
+
+from __future__ import annotations
+
+from maestro_agents.base import MaestroAgent
+
+
+class TestAgent(MaestroAgent):
+    """Generates and executes tests for backend and frontend modules.
+
+    Note: ``__test__ = False`` prevents pytest from collecting this as a test class.
+    """
+
+    __test__ = False
+    """Generates and executes tests for backend and frontend modules.
+
+    Uses SSOT tools to:
+    1. Claim testing-related requirements
+    2. Read contracts to derive test cases
+    3. Write pytest/jest tests via the harness sandbox
+    4. Run tests and report results to the execution log
+    5. Update requirement status to DONE when complete
+    """
+
+    role = "test"
+
+    def system_prompt(self) -> str:
+        return (
+            "You are the Test Agent in the MAESTRO multi-agent system. "
+            "Your job is to write and run tests for the codebase. "
+            "Read the requirements and contracts from the SSOT, then generate "
+            "comprehensive unit and integration tests. "
+            "You have file_read, file_write, and shell_exec tools. Use file_read "
+            "to inspect existing code, file_write to create test files, and "
+            "shell_exec to run pytest/jest and verify results. "
+            "Do NOT use 'cd' in shell commands — the sandbox cwd is already "
+            "the project root. Report test results via the SSOT execution log tools "
+            "and update the requirement status when done."
+        )

maestro_agents-0.1.0/src/maestro_agents/tools.py

@@ -0,0 +1,266 @@
+"""PydanticAI function tools for SSOT read/write operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic_ai import Agent, RunContext
+
+from maestro_harness.validator import Action
+
+from .deps import AgentDeps
+from .permissions import AgentPermissions
+
+
+def register_tools(
+    agent: Agent[AgentDeps, str], permissions: AgentPermissions | None = None
+) -> None:
+    """Register SSOT tools onto a PydanticAI Agent, filtered by permissions.
+
+    Args:
+        agent: The PydanticAI agent to register tools on.
+        permissions: Permission bitmask controlling which tools are available.
+            If None, all tools are registered (backward-compatible default).
+    """
+    perms = permissions or AgentPermissions()
+
+    if perms.read_requirements:
+
+        @agent.tool
+        async def ssot_read_requirements(ctx: RunContext[AgentDeps]) -> str:
+            """Read all pending requirements from the SSOT."""
+            pending = ctx.deps.hub.list_pending()
+            if not pending:
+                return "No pending requirements."
+            lines = []
+            for r in pending:
+                assignee = r.assignee or "unassigned"
+                lines.append(
+                    f"[{r.id}] {r.description} (status={r.status.value}, assignee={assignee})"
+                )
+            return "\n".join(lines)
+
+        @agent.tool
+        async def ssot_get_requirement(ctx: RunContext[AgentDeps], node_id: str) -> str:
+            """Get a specific requirement by ID."""
+            node = ctx.deps.hub.get_requirement(node_id)
+            if node is None:
+                return f"Requirement {node_id} not found."
+            lines = [
+                f"ID: {node.id}",
+                f"Description: {node.description}",
+                f"Status: {node.status.value}",
+            ]
+            if node.assignee:
+                lines.append(f"Assignee: {node.assignee}")
+            if node.acceptance_criteria:
+                lines.append("Acceptance criteria:")
+                for ac in node.acceptance_criteria:
+                    lines.append(f"  - {ac}")
+            if node.dependencies:
+                lines.append(f"Dependencies: {', '.join(node.dependencies)}")
+            return "\n".join(lines)
+
+    if perms.write_requirements:
+
+        @agent.tool
+        async def ssot_add_requirement(
+            ctx: RunContext[AgentDeps],
+            description: str,
+            parent_id: str,
+            acceptance_criteria: list[str] | None = None,
+            dependency_ids: list[str] | None = None,
+        ) -> str:
+            """Add a new requirement to the SSOT. parent_id is REQUIRED.
+
+            dependency_ids must be a list of existing requirement IDs (not descriptions)
+            that must be completed before this task can start.
+            """
+            node = ctx.deps.hub.add_requirement(
+                description=description,
+                parent_id=parent_id,
+                acceptance_criteria=acceptance_criteria,
+                dependencies=dependency_ids,
+                agent_id=ctx.deps.agent_id,
+            )
+            return f"Created requirement {node.id}: {node.description}"
+
+        @agent.tool
+        async def ssot_update_requirement_status(
+            ctx: RunContext[AgentDeps], node_id: str, status: str
+        ) -> str:
+            """Update a requirement's status. Status values: PENDING, IN_PROGRESS, DONE, BLOCKED."""
+            from maestro_ssot.models import ReqStatus
+
+            try:
+                req_status = ReqStatus(status)
+            except ValueError:
+                valid = ", ".join(s.value for s in ReqStatus)
+                return f"Invalid status '{status}'. Valid: {valid}"
+            ctx.deps.hub.update_requirement_status(node_id, req_status, ctx.deps.agent_id)
+            return f"Requirement {node_id} status updated to {status}"
+
+        @agent.tool
+        async def ssot_update_requirement_dependencies(
+            ctx: RunContext[AgentDeps], node_id: str, dependency_ids: list[str]
+        ) -> str:
+            """Update the dependencies of an existing requirement.
+
+            dependency_ids must be a list of existing requirement IDs.
+            """
+            node = ctx.deps.hub.update_requirement_dependencies(
+                node_id, dependency_ids, ctx.deps.agent_id
+            )
+            return f"Requirement {node_id} dependencies updated to {', '.join(node.dependencies)}"
+
+    if perms.read_contracts:
+
+        @agent.tool
+        async def ssot_read_contracts(ctx: RunContext[AgentDeps]) -> str:
+            """Read all contracts from the SSOT."""
+            contracts = ctx.deps.hub._persistence.list_contracts()
+            if not contracts:
+                return "No contracts registered."
+            lines = []
+            for c in contracts:
+                consumers = ", ".join(c.consumers) if c.consumers else "none"
+                lines.append(
+                    f"[{c.id}] {c.name} (owner={c.owner}, v{c.version}, "
+                    f"status={c.status.value}, consumers={consumers})"
+                )
+            return "\n".join(lines)
+
+        @agent.tool
+        async def ssot_get_contract(ctx: RunContext[AgentDeps], contract_id: str) -> str:
+            """Get a specific contract by ID."""
+            contract = ctx.deps.hub.get_contract(contract_id)
+            if contract is None:
+                return f"Contract {contract_id} not found."
+            import json
+
+            lines = [
+                f"ID: {contract.id}",
+                f"Name: {contract.name}",
+                f"Owner: {contract.owner}",
+                f"Version: {contract.version}",
+                f"Status: {contract.status.value}",
+                f"Consumers: {', '.join(contract.consumers) if contract.consumers else 'none'}",
+                f"Schema: {json.dumps(contract.interface_schema)}",
+            ]
+            return "\n".join(lines)
+
+    if perms.write_contracts:
+
+        @agent.tool
+        async def ssot_register_contract(
+            ctx: RunContext[AgentDeps],
+            name: str,
+            consumers: list[str] | None = None,
+            interface_schema: dict[str, Any] | None = None,
+        ) -> str:
+            """Register a new API contract in the SSOT.
+
+            The contract owner is automatically set to this agent.
+            """
+            schema = interface_schema if interface_schema is not None else {}
+            contract = ctx.deps.hub.register_contract(
+                name=name,
+                owner=ctx.deps.agent_id,
+                consumers=consumers,
+                interface_schema=schema,
+            )
+            return f"Registered contract {contract.id}: {contract.name} (v{contract.version})"
+
+        @agent.tool
+        async def ssot_update_contract_schema(
+            ctx: RunContext[AgentDeps], contract_id: str, new_schema: dict[str, Any]
+        ) -> str:
+            """Update a contract's interface schema. This bumps the version."""
+            contract = ctx.deps.hub.update_contract_schema(
+                contract_id, new_schema, ctx.deps.agent_id
+            )
+            return f"Contract {contract_id} updated to v{contract.version}"
+
+    if perms.read_memory:
+
+        @agent.tool
+        async def ssot_read_memory(ctx: RunContext[AgentDeps], key: str) -> str:
+            """Read a value from this agent's working memory."""
+            value = ctx.deps.hub.read_memory(ctx.deps.agent_id, key)
+            if value is None:
+                return f"No memory found for key '{key}'."
+            return value
+
+    if perms.write_memory:
+
+        @agent.tool
+        async def ssot_write_memory(ctx: RunContext[AgentDeps], key: str, value: str) -> str:
+            """Write a key-value pair to this agent's working memory."""
+            ctx.deps.hub.write_memory(ctx.deps.agent_id, key, value)
+            return f"Memory saved: {key}"
+
+    if perms.read_log:
+
+        @agent.tool
+        async def ssot_query_log(ctx: RunContext[AgentDeps], agent_id: str | None = None) -> str:
+            """Query the execution log, optionally filtered by agent_id."""
+            entries = ctx.deps.hub.query_log(agent_id=agent_id)
+            if not entries:
+                return "No log entries found."
+            lines = []
+            for e in entries[:20]:
+                status = e.status.value if hasattr(e.status, "value") else str(e.status)
+                lines.append(
+                    f"[{e.timestamp}] {e.agent_id} {e.action_type} -> {e.target} ({status})"
+                )
+            return "\n".join(lines)
+
+    if perms.read_files:
+
+        @agent.tool
+        async def file_read(ctx: RunContext[AgentDeps], path: str) -> str:
+            """Read the contents of a file from the sandbox."""
+            action = Action(action_type="FILE_READ", target=path, agent_id=ctx.deps.agent_id)
+            result = ctx.deps.harness.execute_action(ctx.deps.agent_id, action)
+            if result.exit_code != 0:
+                return f"Error reading file: {result.stderr}"
+            content = result.stdout
+            if len(content) > 2000:
+                content = content[:2000] + f"\n... ({len(content) - 2000} chars truncated)"
+            return content
+
+    if perms.write_files:
+
+        @agent.tool
+        async def file_write(ctx: RunContext[AgentDeps], path: str, content: str) -> str:
+            """Write content to a file in the sandbox (creates parent dirs if needed)."""
+            action = Action(
+                action_type="FILE_WRITE",
+                target=path,
+                content=content,
+                agent_id=ctx.deps.agent_id,
+            )
+            result = ctx.deps.harness.execute_action(ctx.deps.agent_id, action)
+            if result.exit_code != 0:
+                return f"Error writing file: {result.stderr}"
+            return result.stdout or f"File written: {path}"
+
+    if perms.execute_shell:
+
+        @agent.tool
+        async def shell_exec(ctx: RunContext[AgentDeps], command: str) -> str:
+            """Execute a shell command in the sandbox and return stdout/stderr."""
+            action = Action(command=command, agent_id=ctx.deps.agent_id)
+            result = ctx.deps.harness.execute_action(ctx.deps.agent_id, action)
+            lines = [f"exit_code: {result.exit_code}"]
+            if result.stdout:
+                stdout = result.stdout
+                if len(stdout) > 2000:
+                    stdout = stdout[:2000] + f"\n... ({len(stdout) - 2000} chars truncated)"
+                lines.append(f"stdout:\n{stdout}")
+            if result.stderr:
+                stderr = result.stderr
+                if len(stderr) > 1000:
+                    stderr = stderr[:1000] + f"\n... ({len(stderr) - 1000} chars truncated)"
+                lines.append(f"stderr:\n{stderr}")
+            return "\n".join(lines)

maestro_agents-0.1.0/tests/conftest.py

@@ -0,0 +1,16 @@
+"""Shared fixtures for maestro-agents tests."""
+
+import pytest
+
+from maestro_harness.harness import Harness
+from maestro_ssot.hub import SSOTHub
+
+
+@pytest.fixture
+def hub() -> SSOTHub:
+    return SSOTHub(":memory:")
+
+
+@pytest.fixture
+def harness() -> Harness:
+    return Harness("configs/harness_policy.yaml", sandbox_root=".")

maestro_agents-0.1.0/tests/test_agent_base.py

@@ -0,0 +1,63 @@
+"""Tests for MaestroAgent base class."""
+
+from __future__ import annotations
+
+from maestro_agents.base import AgentResult, MaestroAgent
+from maestro_agents.deps import AgentDeps
+from maestro_agents.permissions import AgentPermissions
+from maestro_harness.harness import Harness
+from maestro_ssot.hub import SSOTHub
+
+
+class TestAgentResult:
+    def test_success_result(self) -> None:
+        r = AgentResult(output="done")
+        assert r.success
+        assert r.error is None
+
+    def test_error_result(self) -> None:
+        r = AgentResult(output="", success=False, error="boom")
+        assert not r.success
+        assert r.error == "boom"
+
+
+class TestAgentDeps:
+    def test_deps_fields(self, hub: SSOTHub, harness: Harness) -> None:
+        deps = AgentDeps(hub=hub, harness=harness, agent_id="test", role="generic")
+        assert deps.agent_id == "test"
+        assert deps.role == "generic"
+        assert deps.memory == {}
+
+
+class TestMaestroAgent:
+    def test_init(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = MaestroAgent("test-agent", hub, harness)
+        assert agent.agent_id == "test-agent"
+        assert agent.hub is hub
+        assert agent.harness is harness
+        assert agent.role == "generic"
+
+    def test_default_system_prompt(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = MaestroAgent("test-agent", hub, harness)
+        assert "MAESTRO" in agent.system_prompt()
+
+    def test_permissions_all_true_by_default(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = MaestroAgent("test-agent", hub, harness)
+        toolset = agent._agent._function_toolset  # type: ignore[attr-defined]
+        tool_names = {name for name in toolset.tools}
+        assert "file_read" in tool_names
+        assert "file_write" in tool_names
+        assert "shell_exec" in tool_names
+
+    def test_permissions_restrict_file_tools(self, hub: SSOTHub, harness: Harness) -> None:
+        restricted = AgentPermissions(
+            read_files=False, write_files=False, execute_shell=False
+        )
+        agent = MaestroAgent("restricted", hub, harness, permissions=restricted)
+        toolset = agent._agent._function_toolset  # type: ignore[attr-defined]
+        tool_names = {name for name in toolset.tools}
+        assert "file_read" not in tool_names
+        assert "file_write" not in tool_names
+        assert "shell_exec" not in tool_names
+        # SSOT tools should still be present
+        assert "ssot_read_requirements" in tool_names

maestro_agents-0.1.0/tests/test_backend_agent.py

@@ -0,0 +1,23 @@
+"""Tests for BackendAgent."""
+
+from __future__ import annotations
+
+from maestro_agents.backend import BackendAgent
+from maestro_harness.harness import Harness
+from maestro_ssot.hub import SSOTHub
+
+
+class TestBackendAgent:
+    def test_role(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = BackendAgent("backend-1", hub, harness)
+        assert agent.role == "backend"
+
+    def test_system_prompt(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = BackendAgent("backend-1", hub, harness)
+        prompt = agent.system_prompt()
+        assert "Backend Agent" in prompt
+        assert "implement" in prompt.lower()
+
+    def test_agent_id(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = BackendAgent("backend-1", hub, harness)
+        assert agent.agent_id == "backend-1"

maestro_agents-0.1.0/tests/test_contract_validator.py

@@ -0,0 +1,49 @@
+"""Tests for the non-LLM contract validator."""
+
+from __future__ import annotations
+
+from maestro_agents.contract_validator import validate_contracts
+from maestro_harness.harness import Harness
+from maestro_ssot.hub import SSOTHub
+from maestro_ssot.models import ContractStatus
+
+
+class TestContractValidator:
+    def test_empty_contracts_valid(self, hub: SSOTHub, harness: Harness) -> None:
+        result = validate_contracts(hub)
+        assert result.valid
+        assert result.violations == []
+
+    def test_stable_contract_without_schema(self, hub: SSOTHub, harness: Harness) -> None:
+        contract = hub.register_contract("API", owner="backend_agent", interface_schema={})
+        hub.contracts.update_status(contract.id, ContractStatus.STABLE)
+        result = validate_contracts(hub)
+        assert not result.valid
+        assert any("empty interface_schema" in v.message for v in result.violations)
+
+    def test_draft_consumer_of_stable_contract(self, hub: SSOTHub, harness: Harness) -> None:
+        draft = hub.register_contract(
+            "DraftAPI", owner="backend_agent", interface_schema={"type": "object"}
+        )
+        active = hub.register_contract(
+            "ActiveAPI",
+            owner="frontend_agent",
+            consumers=[draft.id],
+            interface_schema={"type": "object"},
+        )
+        hub.contracts.update_status(active.id, ContractStatus.STABLE)
+
+        result = validate_contracts(hub)
+        assert not result.valid
+        assert any("DRAFT contract" in v.message for v in result.violations)
+
+    def test_valid_stable_contract_with_schema(self, hub: SSOTHub, harness: Harness) -> None:
+        contract = hub.register_contract(
+            "GoodAPI",
+            owner="backend_agent",
+            interface_schema={"type": "object", "properties": {"id": {"type": "string"}}},
+        )
+        hub.contracts.update_status(contract.id, ContractStatus.STABLE)
+
+        result = validate_contracts(hub)
+        assert result.valid

maestro_agents-0.1.0/tests/test_planning_agent.py

@@ -0,0 +1,23 @@
+"""Tests for PlanningAgent."""
+
+from __future__ import annotations
+
+from maestro_agents.planning import PlanningAgent
+from maestro_harness.harness import Harness
+from maestro_ssot.hub import SSOTHub
+
+
+class TestPlanningAgent:
+    def test_role(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = PlanningAgent("planner-1", hub, harness)
+        assert agent.role == "planner"
+
+    def test_system_prompt(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = PlanningAgent("planner-1", hub, harness)
+        prompt = agent.system_prompt()
+        assert "Planning Agent" in prompt
+        assert "decompose" in prompt.lower()
+
+    def test_agent_id(self, hub: SSOTHub, harness: Harness) -> None:
+        agent = PlanningAgent("planner-1", hub, harness)
+        assert agent.agent_id == "planner-1"