open-agent-protocol 0.1.0__tar.gz

open_agent_protocol-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environment
+venv/
+.venv/
+
+# Pytest
+.pytest_cache/
+
+# Typing
+.mypy_cache/
+.pyright/
+
+# Editor
+.vscode/
+.idea/
+
+# OS
+.DS_Store

open_agent_protocol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OAP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

open_agent_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: open-agent-protocol
+Version: 0.1.0
+Summary: Open Agent Protocol — a routing layer for inter-agent task handoff
+Project-URL: Repository, https://github.com/Adam-Abinsha-vahab-Baker/OAP
+Project-URL: Issues, https://github.com/Adam-Abinsha-vahab-Baker/OAP/issues
+Author: OAP Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,llm,multi-agent,routing,task-handoff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: rich<14.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OAP — Open Agent Protocol
+
+A lightweight routing layer for passing tasks between AI agents.
+
+OAP defines a standard envelope format (`TaskEnvelope`) and a router that dispatches tasks to the right agent based on capabilities or explicit handoff instructions.
+
+## Installation
+
+```bash
+pip install open-agent-protocol
+```
+
+## Quick start
+
+```python
+from oap import TaskEnvelope, OAPRouter
+from oap.adapters.http import HTTPAdapter
+
+router = OAPRouter()
+router.register(
+    "research-agent",
+    HTTPAdapter(agent_id="research-agent", base_url="http://localhost:9000"),
+    capabilities=["research", "search", "find"],
+)
+
+envelope = TaskEnvelope(goal="research the best vector databases")
+result = await router.route(envelope)
+print(result.memory["last_result"])
+```
+
+## CLI
+
+```bash
+# Create a new task envelope
+oap init "research the best vector databases" --output task.json
+
+# Route it to an HTTP agent
+oap register research-agent http://localhost:9000 --capabilities "research,search" task.json --output result.json
+
+# Inspect the result
+oap inspect result.json
+
+# Validate envelope structure
+oap validate result.json
+
+# Route using built-in demo agents
+oap route task.json
+
+# List demo agents
+oap agents
+```
+
+## Concepts
+
+- **TaskEnvelope** — the standard task object passed between agents. Contains the goal, memory, steps taken, and optional constraints.
+- **OAPRouter** — selects the best registered agent for a given envelope and invokes it.
+- **AgentAdapter** — translates between the envelope format and an agent's native interface.
+- **HTTPAdapter** — built-in adapter for agents that expose a `POST /invoke` endpoint.
+
+## License
+
+MIT

open_agent_protocol-0.1.0/README.md

@@ -0,0 +1,62 @@
+# OAP — Open Agent Protocol
+
+A lightweight routing layer for passing tasks between AI agents.
+
+OAP defines a standard envelope format (`TaskEnvelope`) and a router that dispatches tasks to the right agent based on capabilities or explicit handoff instructions.
+
+## Installation
+
+```bash
+pip install open-agent-protocol
+```
+
+## Quick start
+
+```python
+from oap import TaskEnvelope, OAPRouter
+from oap.adapters.http import HTTPAdapter
+
+router = OAPRouter()
+router.register(
+    "research-agent",
+    HTTPAdapter(agent_id="research-agent", base_url="http://localhost:9000"),
+    capabilities=["research", "search", "find"],
+)
+
+envelope = TaskEnvelope(goal="research the best vector databases")
+result = await router.route(envelope)
+print(result.memory["last_result"])
+```
+
+## CLI
+
+```bash
+# Create a new task envelope
+oap init "research the best vector databases" --output task.json
+
+# Route it to an HTTP agent
+oap register research-agent http://localhost:9000 --capabilities "research,search" task.json --output result.json
+
+# Inspect the result
+oap inspect result.json
+
+# Validate envelope structure
+oap validate result.json
+
+# Route using built-in demo agents
+oap route task.json
+
+# List demo agents
+oap agents
+```
+
+## Concepts
+
+- **TaskEnvelope** — the standard task object passed between agents. Contains the goal, memory, steps taken, and optional constraints.
+- **OAPRouter** — selects the best registered agent for a given envelope and invokes it.
+- **AgentAdapter** — translates between the envelope format and an agent's native interface.
+- **HTTPAdapter** — built-in adapter for agents that expose a `POST /invoke` endpoint.
+
+## License
+
+MIT

open_agent_protocol-0.1.0/oap/__init__.py

@@ -0,0 +1,11 @@
+from oap.envelope import Constraints, Handoff, Step, TaskEnvelope
+from oap.router import OAPRouter, RoutingError
+
+__all__ = [
+    "TaskEnvelope",
+    "Step",
+    "Constraints",
+    "Handoff",
+    "OAPRouter",
+    "RoutingError",
+]

open_agent_protocol-0.1.0/oap/adapters/__init__.py

@@ -0,0 +1,4 @@
+from oap.adapters.base import AgentAdapter
+from oap.adapters.http import HTTPAdapter
+
+__all__ = ["AgentAdapter", "HTTPAdapter"]

open_agent_protocol-0.1.0/oap/adapters/base.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Any
+from oap.envelope import TaskEnvelope
+
+
+class AgentAdapter(ABC):
+
+    @abstractmethod
+    def to_agent_format(self, envelope: TaskEnvelope) -> Any:
+        """Translate a TaskEnvelope into whatever format this agent expects."""
+        ...
+
+    @abstractmethod
+    async def invoke(self, agent_input: Any) -> Any:
+        """Call the agent and return its raw output."""
+        ...
+
+    @abstractmethod
+    def to_envelope(self, agent_output: Any, previous: TaskEnvelope) -> TaskEnvelope:
+        """Translate the agent's output back into a TaskEnvelope."""
+        ...

open_agent_protocol-0.1.0/oap/adapters/http.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+from typing import Any
+from oap.adapters.base import AgentAdapter
+from oap.envelope import TaskEnvelope
+from oap.transport.http import HTTPTransport
+
+
+class HTTPAdapter(AgentAdapter):
+    """Adapter for any agent that exposes a POST /invoke endpoint."""
+
+    def __init__(self, agent_id: str, base_url: str, timeout: float = 30.0):
+        self.agent_id = agent_id
+        self.transport = HTTPTransport(base_url=base_url, timeout=timeout)
+
+    def to_agent_format(self, envelope: TaskEnvelope) -> TaskEnvelope:
+        return envelope
+
+    async def invoke(self, agent_input: Any) -> dict:
+        return await self.transport.invoke(agent_input)
+
+    def to_envelope(self, agent_output: dict, previous: TaskEnvelope) -> TaskEnvelope:
+        updated = previous.model_copy(deep=True)
+
+        if "memory" in agent_output:
+            updated.memory.update(agent_output["memory"])
+
+        if "result" in agent_output:
+            updated.memory["last_result"] = agent_output["result"]
+
+        if "handoff" in agent_output and agent_output["handoff"]:
+            h = agent_output["handoff"]
+            updated.with_handoff(
+                next_agent=h["next_agent"],
+                reason=h.get("reason", ""),
+                partial_result=h.get("partial_result"),
+            )
+
+        return updated

open_agent_protocol-0.1.0/oap/adapters/mock.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from typing import Any
+from oap.adapters.base import AgentAdapter
+from oap.envelope import TaskEnvelope
+
+
+class MockAgentAdapter(AgentAdapter):
+    """A fake agent that returns a canned response. Used for testing."""
+
+    def __init__(self, agent_id: str, response: str = "Mock result"):
+        self.agent_id = agent_id
+        self.response = response
+
+    def to_agent_format(self, envelope: TaskEnvelope) -> dict:
+        return {"goal": envelope.goal, "memory": envelope.memory}
+
+    async def invoke(self, agent_input: Any) -> dict:
+        return {"result": self.response, "goal": agent_input["goal"]}
+
+    def to_envelope(self, agent_output: Any, previous: TaskEnvelope) -> TaskEnvelope:
+        updated = previous.model_copy(deep=True)
+        updated.memory["last_result"] = agent_output.get("result")
+        return updated

open_agent_protocol-0.1.0/oap/cli.py

@@ -0,0 +1,195 @@
+import asyncio
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.syntax import Syntax
+from rich.table import Table
+
+from oap.envelope import TaskEnvelope
+from oap.router import OAPRouter, RoutingError
+from oap.adapters.mock import MockAgentAdapter
+from oap.adapters.http import HTTPAdapter
+
+app = typer.Typer(
+    name="oap",
+    help="Open Agent Protocol — route tasks between agents.",
+    add_completion=False,
+)
+console = Console()
+
+
+def _build_demo_router() -> OAPRouter:
+    """A router pre-loaded with mock agents for local testing."""
+    router = OAPRouter()
+    router.register(
+        "research-agent",
+        MockAgentAdapter("research-agent", response="Found 5 relevant sources."),
+        capabilities=["research", "find", "search", "summarise"],
+    )
+    router.register(
+        "coding-agent",
+        MockAgentAdapter("coding-agent", response="Code written and tested."),
+        capabilities=["code", "implement", "debug", "refactor"],
+    )
+    return router
+
+
+@app.command()
+def init(
+    goal: str = typer.Argument(..., help="The task goal for this envelope"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Save envelope to file"),
+):
+    """Create a new TaskEnvelope and print it."""
+    envelope = TaskEnvelope(goal=goal)
+    json_str = envelope.model_dump_json(indent=2)
+
+    console.print(Syntax(json_str, "json", theme="monokai"))
+
+    if output:
+        output.write_text(json_str)
+        console.print(f"\n[green]Saved to {output}[/green]")
+
+
+@app.command()
+def inspect(
+    file: Path = typer.Argument(..., help="Path to a TaskEnvelope JSON file"),
+):
+    """Inspect a TaskEnvelope file and summarise its contents."""
+    if not file.exists():
+        console.print(f"[red]File not found: {file}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        envelope = TaskEnvelope.model_validate_json(file.read_text())
+    except Exception as e:
+        console.print(f"[red]Invalid envelope: {e}[/red]")
+        raise typer.Exit(1)
+
+    console.print(f"\n[bold]Envelope[/bold] [dim]{envelope.id}[/dim]")
+    console.print(f"[bold]Goal:[/bold] {envelope.goal}")
+    console.print(f"[bold]Version:[/bold] {envelope.version}")
+
+    table = Table(show_header=True, header_style="bold dim")
+    table.add_column("Field")
+    table.add_column("Value")
+    table.add_row("Steps taken", str(len(envelope.steps_taken)))
+    table.add_row("Memory keys", ", ".join(envelope.memory.keys()) or "—")
+    table.add_row("Max cost", str(envelope.constraints.max_cost_usd or "—"))
+    table.add_row("Allowed tools", ", ".join(envelope.constraints.allowed_tools or []) or "—")
+    table.add_row("Handoff", envelope.handoff.next_agent if envelope.handoff else "—")
+    console.print(table)
+
+    if envelope.steps_taken:
+        console.print("\n[bold]Steps:[/bold]")
+        for i, step in enumerate(envelope.steps_taken, 1):
+            console.print(f"  {i}. [cyan]{step.agent_id}[/cyan] → {step.action}")
+
+
+@app.command()
+def validate(
+    file: Path = typer.Argument(..., help="Path to a TaskEnvelope JSON file"),
+):
+    """Validate a TaskEnvelope file against the schema."""
+    if not file.exists():
+        console.print(f"[red]File not found: {file}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        TaskEnvelope.model_validate_json(file.read_text())
+        console.print("[green]Valid envelope.[/green]")
+    except Exception as e:
+        console.print(f"[red]Invalid:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@app.command()
+def route(
+    file: Path = typer.Argument(..., help="Path to a TaskEnvelope JSON file"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Save result envelope to file"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show which agent would handle it, without invoking"),
+):
+    """Route a TaskEnvelope to the appropriate agent."""
+    if not file.exists():
+        console.print(f"[red]File not found: {file}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        envelope = TaskEnvelope.model_validate_json(file.read_text())
+    except Exception as e:
+        console.print(f"[red]Invalid envelope: {e}[/red]")
+        raise typer.Exit(1)
+
+    router = _build_demo_router()
+
+    try:
+        agent_id = router.select_agent(envelope)
+    except RoutingError as e:
+        console.print(f"[red]Routing failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    if dry_run:
+        console.print(f"[yellow]Dry run:[/yellow] would route to [cyan]{agent_id}[/cyan]")
+        return
+
+    console.print(f"[dim]Routing to[/dim] [cyan]{agent_id}[/cyan]...")
+    result = asyncio.run(router.route(envelope))
+
+    json_str = result.model_dump_json(indent=2)
+    console.print(Syntax(json_str, "json", theme="monokai"))
+
+    if output:
+        output.write_text(json_str)
+        console.print(f"\n[green]Saved to {output}[/green]")
+
+@app.command()
+def register(
+    agent_id: str = typer.Argument(..., help="Unique name for this agent"),
+    url: str = typer.Argument(..., help="Base URL of the agent's HTTP server"),
+    capabilities: str = typer.Option(..., "--capabilities", "-c", help="Comma-separated capability keywords"),
+    file: Path = typer.Argument(..., help="Envelope file to route"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Save result envelope to file"),
+):
+    """Route an envelope to a specific HTTP agent by URL."""
+    if not file.exists():
+        console.print(f"[red]File not found: {file}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        envelope = TaskEnvelope.model_validate_json(file.read_text())
+    except Exception as e:
+        console.print(f"[red]Invalid envelope: {e}[/red]")
+        raise typer.Exit(1)
+
+    caps = [c.strip() for c in capabilities.split(",")]
+    router = OAPRouter()
+    router.register(agent_id, HTTPAdapter(agent_id=agent_id, base_url=url), caps)
+
+    console.print(f"[dim]Routing to[/dim] [cyan]{agent_id}[/cyan] at [dim]{url}[/dim]...")
+    result = asyncio.run(router.route(envelope))
+
+    json_str = result.model_dump_json(indent=2)
+    console.print(Syntax(json_str, "json", theme="monokai"))
+
+    if output:
+        output.write_text(json_str)
+        console.print(f"\n[green]Saved to {output}[/green]")
+        
+@app.command()
+def agents():
+    """List all registered agents and their capabilities."""
+    router = _build_demo_router()
+
+    table = Table(show_header=True, header_style="bold dim")
+    table.add_column("Agent ID")
+    table.add_column("Capabilities")
+
+    for entry in router.list_agents():
+        table.add_row(
+            f"[cyan]{entry['id']}[/cyan]",
+            ", ".join(entry["capabilities"]),
+        )
+
+    console.print(table)

open_agent_protocol-0.1.0/oap/envelope.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+from pydantic import BaseModel, Field
+
+
+class Step(BaseModel):
+    agent_id: str
+    action: str
+    result: Any = None
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class Constraints(BaseModel):
+    max_cost_usd: float | None = None
+    allowed_tools: list[str] | None = None
+    deadline_ms: int | None = None
+
+
+class Handoff(BaseModel):
+    next_agent: str
+    reason: str
+    partial_result: Any = None
+
+
+class TaskEnvelope(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    version: str = "0.1"
+    goal: str
+    memory: dict[str, Any] = Field(default_factory=dict)
+    steps_taken: list[Step] = Field(default_factory=list)
+    constraints: Constraints = Field(default_factory=Constraints)
+    handoff: Handoff | None = None
+
+    def add_step(self, agent_id: str, action: str, result: Any = None) -> None:
+        self.steps_taken.append(Step(agent_id=agent_id, action=action, result=result))
+
+    def with_handoff(self, next_agent: str, reason: str, partial_result: Any = None) -> "TaskEnvelope":
+        self.handoff = Handoff(next_agent=next_agent, reason=reason, partial_result=partial_result)
+        return self

open_agent_protocol-0.1.0/oap/router.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+import re
+from datetime import datetime, timezone
+from typing import Any
+from oap.envelope import TaskEnvelope
+from oap.adapters.base import AgentAdapter
+
+
+class RoutingError(Exception):
+    pass
+
+
+class OAPRouter:
+    def __init__(self):
+        self._agents: dict[str, AgentAdapter] = {}
+        self._capabilities: dict[str, list[str]] = {}
+
+    def register(self, agent_id: str, adapter: AgentAdapter, capabilities: list[str]) -> None:
+        """Register an agent with its capabilities."""
+        self._agents[agent_id] = adapter
+        self._capabilities[agent_id] = [c.lower() for c in capabilities]
+
+    def list_agents(self) -> list[dict[str, Any]]:
+        """Return all registered agents and their capabilities."""
+        return [
+            {"id": agent_id, "capabilities": caps}
+            for agent_id, caps in self._capabilities.items()
+        ]
+
+    def select_agent(self, envelope: TaskEnvelope) -> str:
+        """Pick the best agent for this envelope.
+
+        Priority:
+        1. Explicit handoff.next_agent in the envelope
+        2. Capability match against goal keywords (most matches wins)
+        3. Raise RoutingError if nothing matches or there is a tie
+        """
+        if envelope.handoff and envelope.handoff.next_agent:
+            agent_id = envelope.handoff.next_agent
+            if agent_id not in self._agents:
+                raise RoutingError(f"Requested agent '{agent_id}' is not registered.")
+            return agent_id
+
+        return self._match_by_capability(envelope.goal)
+
+    def _match_by_capability(self, goal: str) -> str:
+        """Score each agent by how many capability keywords appear in the goal."""
+        goal_lower = goal.lower()
+        scores: dict[str, int] = {}
+
+        for agent_id, caps in self._capabilities.items():
+            score = sum(
+                1 for cap in caps
+                if re.search(rf"\b{re.escape(cap)}\b", goal_lower)
+            )
+            scores[agent_id] = score
+
+        if not scores:
+            raise RoutingError("No agents are registered.")
+
+        best_score = max(scores.values())
+
+        if best_score == 0:
+            raise RoutingError(
+                f"No agent matched the goal: '{goal}'\n"
+                f"Registered capabilities: {self._capabilities}"
+            )
+
+        winners = [aid for aid, score in scores.items() if score == best_score]
+        if len(winners) > 1:
+            raise RoutingError(
+                f"Ambiguous routing for goal: '{goal}'\n"
+                f"Tied agents: {winners} — add a handoff.next_agent to disambiguate."
+            )
+
+        return winners[0]
+
+    async def route(self, envelope: TaskEnvelope) -> TaskEnvelope:
+        """Route an envelope to the correct agent and return the updated envelope."""
+        agent_id = self.select_agent(envelope)
+        adapter = self._agents[agent_id]
+
+        agent_input = adapter.to_agent_format(envelope)
+        agent_output = await adapter.invoke(agent_input)
+        result = adapter.to_envelope(agent_output, envelope)
+
+        result.add_step(
+            agent_id=agent_id,
+            action=f"Routed to {agent_id}",
+            result=agent_output,
+        )
+        return result

open_agent_protocol-0.1.0/oap/transport/__init__.py

@@ -0,0 +1,3 @@
+from oap.transport.http import HTTPTransport
+
+__all__ = ["HTTPTransport"]

open_agent_protocol-0.1.0/oap/transport/http.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+import httpx
+from oap.envelope import TaskEnvelope
+
+
+class HTTPTransport:
+    def __init__(self, base_url: str, timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    async def invoke(self, envelope: TaskEnvelope) -> dict:
+        payload = envelope.model_dump(mode="json")
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                f"{self.base_url}/invoke",
+                json=payload,
+            )
+            response.raise_for_status()
+            return response.json()

open_agent_protocol-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "open-agent-protocol"
+version = "0.1.0"
+description = "Open Agent Protocol — a routing layer for inter-agent task handoff"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "OAP Contributors" }]
+keywords = ["agents", "routing", "llm", "multi-agent", "task-handoff"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.12,<1.0",
+    "pydantic>=2.0,<3.0",
+    "httpx>=0.27,<1.0",
+    "rich>=13.0,<14.0",
+]
+
+[project.urls]
+Repository = "https://github.com/Adam-Abinsha-vahab-Baker/OAP"
+Issues = "https://github.com/Adam-Abinsha-vahab-Baker/OAP/issues"
+
+[project.scripts]
+oap = "oap.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["oap"]

open_agent_protocol-0.1.0/tests/fake_agent_server.py

@@ -0,0 +1,45 @@
+"""
+A minimal fake agent server for integration testing.
+Run with: python tests/fake_agent_server.py
+It listens on localhost:9999 and responds to POST /invoke
+"""
+import json
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+
+class FakeAgentHandler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        if self.path != "/invoke":
+            self.send_response(404)
+            self.end_headers()
+            return
+
+        length = int(self.headers["Content-Length"])
+        body = json.loads(self.rfile.read(length))
+
+        goal = body.get("goal", "")
+        response = {
+            "result": f"Fake agent processed: {goal}",
+            "memory": {
+                "processed_by": "fake-agent",
+                "goal_length": len(goal),
+            },
+        }
+
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(response).encode())
+
+    def log_message(self, format, *args):
+        pass  # silence request logs during tests
+
+
+def run(port: int = 9999):
+    server = HTTPServer(("localhost", port), FakeAgentHandler)
+    print(f"Fake agent running on http://localhost:{port}")
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    run()

open_agent_protocol-0.1.0/tests/test_cli.py

@@ -0,0 +1,131 @@
+import json
+import threading
+import pytest
+from typer.testing import CliRunner
+from tests.fake_agent_server import FakeAgentHandler, HTTPServer
+from oap.cli import app
+
+runner = CliRunner()
+
+_CLI_TEST_PORT = 19998
+
+
+@pytest.fixture(scope="module")
+def fake_server():
+    server = HTTPServer(("localhost", _CLI_TEST_PORT), FakeAgentHandler)
+    thread = threading.Thread(target=server.serve_forever)
+    thread.daemon = True
+    thread.start()
+    yield f"http://localhost:{_CLI_TEST_PORT}"
+    server.shutdown()
+
+
+def test_init_prints_envelope():
+    result = runner.invoke(app, ["init", "test goal"])
+    assert result.exit_code == 0
+    assert "test goal" in result.output
+
+
+def test_init_saves_to_file(tmp_path):
+    out = tmp_path / "envelope.json"
+    result = runner.invoke(app, ["init", "save this goal", "--output", str(out)])
+    assert result.exit_code == 0
+    assert out.exists()
+    data = json.loads(out.read_text())
+    assert data["goal"] == "save this goal"
+
+
+def test_inspect_valid_file(tmp_path):
+    out = tmp_path / "envelope.json"
+    runner.invoke(app, ["init", "inspect me", "--output", str(out)])
+    result = runner.invoke(app, ["inspect", str(out)])
+    assert result.exit_code == 0
+    assert "inspect me" in result.output
+
+
+def test_inspect_missing_file():
+    result = runner.invoke(app, ["inspect", "/nonexistent/path.json"])
+    assert result.exit_code == 1
+
+
+def test_validate_valid_file(tmp_path):
+    out = tmp_path / "envelope.json"
+    runner.invoke(app, ["init", "valid goal", "--output", str(out)])
+    result = runner.invoke(app, ["validate", str(out)])
+    assert result.exit_code == 0
+    assert "Valid" in result.output
+
+
+def test_validate_invalid_file(tmp_path):
+    bad = tmp_path / "bad.json"
+    bad.write_text('{"not": "an envelope"}')
+    result = runner.invoke(app, ["validate", str(bad)])
+    assert result.exit_code == 1
+
+
+def test_route_dry_run(tmp_path):
+    out = tmp_path / "task.json"
+    runner.invoke(app, ["init", "research neural networks", "--output", str(out)])
+    result = runner.invoke(app, ["route", str(out), "--dry-run"])
+    assert result.exit_code == 0
+    assert "research-agent" in result.output
+
+
+def test_route_produces_result(tmp_path):
+    task = tmp_path / "task.json"
+    result_file = tmp_path / "result.json"
+    runner.invoke(app, ["init", "debug my python code", "--output", str(task)])
+    result = runner.invoke(app, ["route", str(task), "--output", str(result_file)])
+    assert result.exit_code == 0
+    assert result_file.exists()
+    data = json.loads(result_file.read_text())
+    assert len(data["steps_taken"]) == 1
+    assert data["steps_taken"][0]["agent_id"] == "coding-agent"
+
+
+def test_agents_lists_registered():
+    result = runner.invoke(app, ["agents"])
+    assert result.exit_code == 0
+    assert "research-agent" in result.output
+    assert "coding-agent" in result.output
+
+
+# --- register command ---
+
+def test_register_routes_to_http_agent(tmp_path, fake_server):
+    task = tmp_path / "task.json"
+    result_file = tmp_path / "result.json"
+    runner.invoke(app, ["init", "research the best vector databases", "--output", str(task)])
+
+    result = runner.invoke(app, [
+        "register", "research-agent", fake_server,
+        "--capabilities", "research,find,search",
+        str(task),
+        "--output", str(result_file),
+    ])
+
+    assert result.exit_code == 0, result.output
+    assert result_file.exists()
+    data = json.loads(result_file.read_text())
+    assert len(data["steps_taken"]) == 1
+    assert data["steps_taken"][0]["agent_id"] == "research-agent"
+
+
+def test_register_missing_file(fake_server):
+    result = runner.invoke(app, [
+        "register", "research-agent", fake_server,
+        "--capabilities", "research",
+        "/nonexistent/task.json",
+    ])
+    assert result.exit_code == 1
+
+
+def test_register_invalid_envelope(tmp_path, fake_server):
+    bad = tmp_path / "bad.json"
+    bad.write_text('{"not": "valid"}')
+    result = runner.invoke(app, [
+        "register", "research-agent", fake_server,
+        "--capabilities", "research",
+        str(bad),
+    ])
+    assert result.exit_code == 1

open_agent_protocol-0.1.0/tests/test_envelope.py

@@ -0,0 +1,63 @@
+import pytest
+from oap.envelope import TaskEnvelope, Step, Constraints, Handoff
+
+
+def test_default_envelope():
+    e = TaskEnvelope(goal="test goal")
+    assert e.goal == "test goal"
+    assert e.version == "0.1"
+    assert e.memory == {}
+    assert e.steps_taken == []
+    assert e.handoff is None
+
+
+def test_envelope_id_is_unique():
+    a = TaskEnvelope(goal="task a")
+    b = TaskEnvelope(goal="task b")
+    assert a.id != b.id
+
+
+def test_add_step():
+    e = TaskEnvelope(goal="test")
+    e.add_step(agent_id="research-agent", action="searched web", result="5 results")
+    assert len(e.steps_taken) == 1
+    assert e.steps_taken[0].agent_id == "research-agent"
+    assert e.steps_taken[0].result == "5 results"
+
+
+def test_add_multiple_steps():
+    e = TaskEnvelope(goal="test")
+    e.add_step("agent-a", "step 1")
+    e.add_step("agent-b", "step 2")
+    assert len(e.steps_taken) == 2
+
+
+def test_with_handoff():
+    e = TaskEnvelope(goal="test")
+    e.with_handoff(next_agent="coding-agent", reason="needs code", partial_result={"found": True})
+    assert e.handoff is not None
+    assert e.handoff.next_agent == "coding-agent"
+    assert e.handoff.reason == "needs code"
+    assert e.handoff.partial_result == {"found": True}
+
+
+def test_serialise_roundtrip():
+    e = TaskEnvelope(goal="roundtrip test")
+    e.add_step("agent-x", "did something", result="ok")
+    json_str = e.model_dump_json()
+    restored = TaskEnvelope.model_validate_json(json_str)
+    assert restored.id == e.id
+    assert restored.goal == e.goal
+    assert len(restored.steps_taken) == 1
+
+
+def test_constraints_defaults():
+    e = TaskEnvelope(goal="test")
+    assert e.constraints.max_cost_usd is None
+    assert e.constraints.allowed_tools is None
+    assert e.constraints.deadline_ms is None
+
+
+def test_invalid_envelope_missing_goal():
+    with pytest.raises(Exception):
+        TaskEnvelope.model_validate({"version": "0.1"})

open_agent_protocol-0.1.0/tests/test_http_adapter.py

@@ -0,0 +1,71 @@
+import pytest
+import threading
+from tests.fake_agent_server import FakeAgentHandler, HTTPServer
+from oap.envelope import TaskEnvelope
+from oap.adapters.http import HTTPAdapter
+from oap.router import OAPRouter
+
+
+PORT = 19999  # high port, avoids permission issues
+
+
+@pytest.fixture(scope="module")
+def fake_server():
+    """Spin up the fake agent server in a background thread for the test module."""
+    server = HTTPServer(("localhost", PORT), FakeAgentHandler)
+    thread = threading.Thread(target=server.serve_forever)
+    thread.daemon = True
+    thread.start()
+    yield f"http://localhost:{PORT}"
+    server.shutdown()
+
+
+async def test_http_adapter_invoke(fake_server):
+    adapter = HTTPAdapter(agent_id="fake-agent", base_url=fake_server)
+    envelope = TaskEnvelope(goal="find the best open source LLMs")
+
+    agent_input = adapter.to_agent_format(envelope)
+    raw_output = await adapter.invoke(agent_input)
+
+    assert "result" in raw_output
+    assert "find the best open source LLMs" in raw_output["result"]
+
+
+async def test_http_adapter_updates_memory(fake_server):
+    adapter = HTTPAdapter(agent_id="fake-agent", base_url=fake_server)
+    envelope = TaskEnvelope(goal="research vector databases")
+
+    agent_input = adapter.to_agent_format(envelope)
+    raw_output = await adapter.invoke(agent_input)
+    result = adapter.to_envelope(raw_output, envelope)
+
+    assert result.memory["last_result"] is not None
+    assert result.memory["processed_by"] == "fake-agent"
+
+
+async def test_http_adapter_preserves_goal(fake_server):
+    adapter = HTTPAdapter(agent_id="fake-agent", base_url=fake_server)
+    envelope = TaskEnvelope(goal="debug my python script")
+
+    agent_input = adapter.to_agent_format(envelope)
+    raw_output = await adapter.invoke(agent_input)
+    result = adapter.to_envelope(raw_output, envelope)
+
+    assert result.goal == envelope.goal
+    assert result.id == envelope.id
+
+
+async def test_router_with_http_adapter(fake_server):
+    router = OAPRouter()
+    router.register(
+        "fake-agent",
+        HTTPAdapter(agent_id="fake-agent", base_url=fake_server),
+        capabilities=["research", "find", "search"],
+    )
+
+    envelope = TaskEnvelope(goal="research the best vector databases")
+    result = await router.route(envelope)
+
+    assert len(result.steps_taken) == 1
+    assert result.steps_taken[0].agent_id == "fake-agent"
+    assert "last_result" in result.memory

open_agent_protocol-0.1.0/tests/test_router.py

@@ -0,0 +1,92 @@
+import pytest
+from oap.envelope import TaskEnvelope
+from oap.router import OAPRouter, RoutingError
+from oap.adapters.mock import MockAgentAdapter
+
+
+def make_router() -> OAPRouter:
+    router = OAPRouter()
+    router.register(
+        "research-agent",
+        MockAgentAdapter("research-agent", response="research done"),
+        capabilities=["research", "find", "search"],
+    )
+    router.register(
+        "coding-agent",
+        MockAgentAdapter("coding-agent", response="code written"),
+        capabilities=["code", "implement", "debug"],
+    )
+    return router
+
+
+def test_list_agents():
+    router = make_router()
+    agents = router.list_agents()
+    ids = [a["id"] for a in agents]
+    assert "research-agent" in ids
+    assert "coding-agent" in ids
+
+
+def test_capability_match_research():
+    router = make_router()
+    e = TaskEnvelope(goal="research the best vector databases")
+    assert router.select_agent(e) == "research-agent"
+
+
+def test_capability_match_coding():
+    router = make_router()
+    e = TaskEnvelope(goal="implement a quick sort algorithm")
+    assert router.select_agent(e) == "coding-agent"
+
+
+def test_explicit_handoff_overrides_capability():
+    router = make_router()
+    e = TaskEnvelope(goal="research something")
+    e.with_handoff(next_agent="coding-agent", reason="user override")
+    assert router.select_agent(e) == "coding-agent"
+
+
+def test_no_match_raises_routing_error():
+    router = make_router()
+    e = TaskEnvelope(goal="make me a sandwich")
+    with pytest.raises(RoutingError):
+        router.select_agent(e)
+
+
+def test_empty_router_raises_routing_error():
+    router = OAPRouter()
+    e = TaskEnvelope(goal="research something")
+    with pytest.raises(RoutingError, match="No agents are registered"):
+        router.select_agent(e)
+
+
+def test_unknown_handoff_agent_raises_routing_error():
+    router = make_router()
+    e = TaskEnvelope(goal="do something")
+    e.with_handoff(next_agent="nonexistent-agent", reason="test")
+    with pytest.raises(RoutingError):
+        router.select_agent(e)
+
+
+async def test_route_updates_memory():
+    router = make_router()
+    e = TaskEnvelope(goal="research neural networks")
+    result = await router.route(e)
+    assert "last_result" in result.memory
+    assert result.memory["last_result"] == "research done"
+
+
+async def test_route_appends_step():
+    router = make_router()
+    e = TaskEnvelope(goal="debug my code")
+    result = await router.route(e)
+    assert len(result.steps_taken) == 1
+    assert result.steps_taken[0].agent_id == "coding-agent"
+
+
+async def test_route_preserves_goal():
+    router = make_router()
+    e = TaskEnvelope(goal="find open source llm frameworks")
+    result = await router.route(e)
+    assert result.goal == e.goal
+    assert result.id == e.id