a2a-agent 0.1.0__tar.gz

a2a_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Judvika
+
+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.

a2a_agent-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: a2a-agent
+Version: 0.1.0
+Summary: MQTT 위에서 도는 커맨더-워커 A2A 오케스트레이션 에이전트
+Author: Judvika
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt
+Requires-Dist: typer
+Requires-Dist: pyyaml
+Dynamic: license-file
+
+# a2a-agent
+
+`a2a-agent`는 MQTT 위에서 커맨더와 워커가 A2A 형식 메시지를 주고받기 위한 작은 명령줄 도구입니다.
+
+현재 `0.1.0`은 설정 파일 저장, 초대 코드 생성과 참여, 워커 역할 기록, 상태 확인을 지원합니다. 실제 작업 전송 명령인 `send`는 아직 자리 표시자입니다.
+
+## 설치
+
+PyPI 배포 후에는 다음처럼 설치할 수 있습니다.
+
+```bash
+python -m pip install a2a-agent
+```
+
+개발 환경에서 소스 코드로 설치하려면 저장소 루트에서 실행합니다.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+## 기본 사용
+
+커맨더 설정을 만듭니다.
+
+```bash
+a2a-agent init --room team --device-name commander --broker-host broker.example.com
+```
+
+워커 초대 코드를 만듭니다.
+
+```bash
+a2a-agent invite device-a
+```
+
+워커 기기에서는 초대 코드로 참여합니다.
+
+```bash
+a2a-agent join "초대코드"
+```
+
+커맨더에서 워커 역할을 기록합니다.
+
+```bash
+a2a-agent set-role device-a research "collect project context"
+```
+
+현재 설정을 확인합니다.
+
+```bash
+a2a-agent status
+```
+
+## 구조
+
+```text
+a2a-agent/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── src/a2a_agent/
+│   ├── cli.py
+│   ├── client.py
+│   ├── config.py
+│   ├── invite.py
+│   ├── protocol.py
+│   └── topics.py
+└── tests/
+```
+
+주요 모듈은 다음 역할을 맡습니다.
+
+- `cli.py`: 명령줄 진입점
+- `config.py`: 로컬 설정 파일 저장과 읽기
+- `invite.py`: 초대 코드 생성과 파싱
+- `protocol.py`: A2A 메시지 자료 구조
+- `topics.py`: MQTT 토픽 문자열 생성
+- `client.py`: `paho-mqtt` 래퍼
+
+## 라이선스
+
+MIT 라이선스를 따릅니다.

a2a_agent-0.1.0/README.md

@@ -0,0 +1,83 @@
+# a2a-agent
+
+`a2a-agent`는 MQTT 위에서 커맨더와 워커가 A2A 형식 메시지를 주고받기 위한 작은 명령줄 도구입니다.
+
+현재 `0.1.0`은 설정 파일 저장, 초대 코드 생성과 참여, 워커 역할 기록, 상태 확인을 지원합니다. 실제 작업 전송 명령인 `send`는 아직 자리 표시자입니다.
+
+## 설치
+
+PyPI 배포 후에는 다음처럼 설치할 수 있습니다.
+
+```bash
+python -m pip install a2a-agent
+```
+
+개발 환경에서 소스 코드로 설치하려면 저장소 루트에서 실행합니다.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+## 기본 사용
+
+커맨더 설정을 만듭니다.
+
+```bash
+a2a-agent init --room team --device-name commander --broker-host broker.example.com
+```
+
+워커 초대 코드를 만듭니다.
+
+```bash
+a2a-agent invite device-a
+```
+
+워커 기기에서는 초대 코드로 참여합니다.
+
+```bash
+a2a-agent join "초대코드"
+```
+
+커맨더에서 워커 역할을 기록합니다.
+
+```bash
+a2a-agent set-role device-a research "collect project context"
+```
+
+현재 설정을 확인합니다.
+
+```bash
+a2a-agent status
+```
+
+## 구조
+
+```text
+a2a-agent/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── src/a2a_agent/
+│   ├── cli.py
+│   ├── client.py
+│   ├── config.py
+│   ├── invite.py
+│   ├── protocol.py
+│   └── topics.py
+└── tests/
+```
+
+주요 모듈은 다음 역할을 맡습니다.
+
+- `cli.py`: 명령줄 진입점
+- `config.py`: 로컬 설정 파일 저장과 읽기
+- `invite.py`: 초대 코드 생성과 파싱
+- `protocol.py`: A2A 메시지 자료 구조
+- `topics.py`: MQTT 토픽 문자열 생성
+- `client.py`: `paho-mqtt` 래퍼
+
+## 라이선스
+
+MIT 라이선스를 따릅니다.

a2a_agent-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a2a-agent"
+version = "0.1.0"
+description = "MQTT 위에서 도는 커맨더-워커 A2A 오케스트레이션 에이전트"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Judvika" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications",
+]
+dependencies = [
+    "paho-mqtt",
+    "typer",
+    "pyyaml",
+]
+
+[project.scripts]
+a2a-agent = "a2a_agent.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]

a2a_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

a2a_agent-0.1.0/src/a2a_agent/__init__.py

@@ -0,0 +1,3 @@
+"""A2A agent package."""
+
+__version__ = "0.1.0"

a2a_agent-0.1.0/src/a2a_agent/cli.py

@@ -0,0 +1,144 @@
+"""Command line entry point for a2a-agent."""
+
+from __future__ import annotations
+
+import typer
+
+from a2a_agent import __version__
+from a2a_agent.config import AgentConfig
+from a2a_agent.config import BrokerConfig
+from a2a_agent.config import DeviceRole
+from a2a_agent.config import load_config
+from a2a_agent.config import save_config
+from a2a_agent.invite import InviteCodeError
+from a2a_agent.invite import create_invite_code
+from a2a_agent.invite import parse_invite_code
+
+
+app = typer.Typer(
+    no_args_is_help=True,
+    invoke_without_command=True,
+    help="A2A messages over MQTT.",
+)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", help="Show package version."),
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.command()
+def init(
+    room: str = typer.Option("default", help="A2A room name."),
+    device_name: str = typer.Option("commander", help="Local device name."),
+    broker_host: str = typer.Option("localhost", help="MQTT broker host."),
+    broker_port: int = typer.Option(1883, help="MQTT broker port."),
+    tls: bool = typer.Option(False, "--tls/--no-tls", help="Use TLS for MQTT."),
+) -> None:
+    path = save_config(
+        AgentConfig(
+            room=room,
+            device_name=device_name,
+            broker=BrokerConfig(host=broker_host, port=broker_port, tls=tls),
+            role="commander",
+        )
+    )
+    typer.echo(f"saved commander config: {path}")
+
+
+@app.command()
+def join(invite_code: str = typer.Argument(..., help="Invite code from commander.")) -> None:
+    try:
+        payload = parse_invite_code(invite_code)
+    except InviteCodeError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    path = save_config(
+        AgentConfig(
+            room=payload["room"],
+            device_name=payload["device_name"],
+            broker=BrokerConfig(
+                host=payload["broker"]["host"],
+                port=payload["broker"]["port"],
+                tls=payload["tls"],
+            ),
+            role="worker",
+            token=payload["token"],
+        )
+    )
+    typer.echo(f"saved worker config: {path}")
+
+
+@app.command()
+def invite(device_name: str = typer.Argument(..., help="Device name to invite.")) -> None:
+    config = load_config()
+    typer.echo(
+        create_invite_code(
+            broker_host=config.broker.host,
+            broker_port=config.broker.port,
+            room=config.room,
+            device_name=device_name,
+            tls=config.broker.tls,
+        )
+    )
+
+
+@app.command("set-role")
+def set_role(
+    device_name: str = typer.Argument(..., help="Worker device name."),
+    role: str = typer.Argument(..., help="Role name managed by commander."),
+    description: str = typer.Argument(..., help="Role description."),
+) -> None:
+    config = load_config()
+    if config.role != "commander":
+        raise typer.BadParameter("set-role requires commander config")
+
+    devices = dict(config.devices)
+    devices[device_name] = DeviceRole(role=role, description=description)
+    path = save_config(
+        AgentConfig(
+            room=config.room,
+            device_name=config.device_name,
+            broker=config.broker,
+            role=config.role,
+            token=config.token,
+            devices=devices,
+        )
+    )
+    typer.echo(f"saved role for {device_name}: {path}")
+
+
+@app.command()
+def send(
+    device_name: str = typer.Argument(..., help="Worker device name."),
+    text: str = typer.Argument(..., help="Message text."),
+) -> None:
+    typer.echo(f"stub: send task to device={device_name} text={text}")
+
+
+@app.command()
+def status() -> None:
+    config = load_config()
+    typer.echo(f"role: {config.role}")
+    typer.echo(f"room: {config.room}")
+    typer.echo(f"device_name: {config.device_name}")
+    typer.echo(
+        "broker: "
+        f"{config.broker.host}:{config.broker.port} "
+        f"tls={str(config.broker.tls).lower()}"
+    )
+
+    if not config.devices:
+        typer.echo("registered devices: none")
+        return
+
+    typer.echo("registered devices:")
+    for device_name, role in sorted(config.devices.items()):
+        typer.echo(
+            f"  - {device_name}: role={role.role} "
+            f"description={role.description}"
+        )

a2a_agent-0.1.0/src/a2a_agent/client.py

@@ -0,0 +1,61 @@
+"""Thin paho-mqtt wrapper.
+
+Importing this module does not connect to a broker. Network access starts only
+when MqttClient.connect() is called.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import paho.mqtt.client as mqtt
+
+
+MessageCallback = Callable[[str, bytes, mqtt.MQTTMessage], None]
+
+
+class MqttClient:
+    def __init__(self) -> None:
+        self._client = mqtt.Client(
+            callback_api_version=mqtt.CallbackAPIVersion.VERSION2
+        )
+
+    def connect(
+        self,
+        host: str,
+        port: int,
+        username: str | None = None,
+        password: str | None = None,
+    ) -> None:
+        if username is not None:
+            self._client.username_pw_set(username, password)
+        self._client.connect(host, port)
+
+    def publish(
+        self,
+        topic: str,
+        payload: str | bytes,
+        qos: int = 1,
+        retain: bool = False,
+    ) -> mqtt.MQTTMessageInfo:
+        return self._client.publish(topic, payload=payload, qos=qos, retain=retain)
+
+    def subscribe(self, topic: str, callback: MessageCallback) -> None:
+        def _handle_message(
+            client: mqtt.Client,
+            userdata: object,
+            message: mqtt.MQTTMessage,
+        ) -> None:
+            callback(message.topic, message.payload, message)
+
+        self._client.message_callback_add(topic, _handle_message)
+        self._client.subscribe(topic, qos=1)
+
+    def loop_start(self) -> None:
+        self._client.loop_start()
+
+    def loop_stop(self) -> None:
+        self._client.loop_stop()
+
+    def disconnect(self) -> None:
+        self._client.disconnect()

a2a_agent-0.1.0/src/a2a_agent/config.py

@@ -0,0 +1,149 @@
+"""Local configuration file handling for a2a-agent."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+import os
+from pathlib import Path
+import platform
+from typing import Any
+
+import yaml
+
+
+CONFIG_PATH = Path.home() / ".a2a-agent" / "config.yaml"
+VALID_ROLES = {"commander", "worker"}
+
+
+@dataclass(frozen=True)
+class BrokerConfig:
+    host: str = "localhost"
+    port: int = 1883
+    tls: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"host": self.host, "port": self.port, "tls": self.tls}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "BrokerConfig":
+        data = data or {}
+        if not isinstance(data, dict):
+            raise ValueError("broker must be a mapping")
+        return cls(
+            host=str(data.get("host", "localhost")),
+            port=int(data.get("port", 1883)),
+            tls=_bool_from_config(data.get("tls", False), "broker.tls"),
+        )
+
+
+@dataclass(frozen=True)
+class DeviceRole:
+    role: str
+    description: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"role": self.role, "description": self.description}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DeviceRole":
+        return cls(
+            role=str(data.get("role", "")),
+            description=str(data.get("description", "")),
+        )
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    room: str = "default"
+    device_name: str = platform.node() or "device"
+    broker: BrokerConfig = BrokerConfig()
+    role: str = "worker"
+    token: str | None = None
+    devices: dict[str, DeviceRole] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.role not in VALID_ROLES:
+            allowed = ", ".join(sorted(VALID_ROLES))
+            raise ValueError(f"role must be one of: {allowed}")
+
+    def to_dict(self) -> dict[str, Any]:
+        data = {
+            "room": self.room,
+            "device_name": self.device_name,
+            "broker": self.broker.to_dict(),
+            "role": self.role,
+            "devices": {
+                name: role.to_dict()
+                for name, role in sorted(self.devices.items())
+            },
+        }
+        if self.token is not None:
+            data["token"] = self.token
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "AgentConfig":
+        data = data or {}
+        if not isinstance(data, dict):
+            raise ValueError("config must be a mapping")
+        devices = data.get("devices", {})
+        if devices is None:
+            devices = {}
+        if not isinstance(devices, dict):
+            raise ValueError("devices must be a mapping")
+
+        return cls(
+            room=str(data.get("room", "default")),
+            device_name=str(data.get("device_name", platform.node() or "device")),
+            broker=BrokerConfig.from_dict(data.get("broker")),
+            role=str(data.get("role", "worker")),
+            token=data.get("token"),
+            devices={
+                str(name): DeviceRole.from_dict(_role_data(role_data))
+                for name, role_data in devices.items()
+            },
+        )
+
+
+def load_config(path: Path | None = None) -> AgentConfig:
+    config_path = path or CONFIG_PATH
+    if not config_path.exists():
+        return AgentConfig()
+
+    raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    return AgentConfig.from_dict(raw)
+
+
+def save_config(config: AgentConfig, path: Path | None = None) -> Path:
+    config_path = path or CONFIG_PATH
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = yaml.safe_dump(config.to_dict(), allow_unicode=True, sort_keys=True)
+    if config_path.exists():
+        config_path.chmod(0o600)
+
+    fd = os.open(config_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as file:
+        file.write(payload)
+    config_path.chmod(0o600)
+    return config_path
+
+
+def _role_data(data: Any) -> dict[str, Any]:
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError("device role entry must be a mapping")
+    return data
+
+
+def _bool_from_config(value: Any, name: str) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.lower()
+        if lowered in {"true", "yes", "1"}:
+            return True
+        if lowered in {"false", "no", "0"}:
+            return False
+    raise ValueError(f"{name} must be a boolean")

a2a_agent-0.1.0/src/a2a_agent/invite.py

@@ -0,0 +1,115 @@
+"""Invite code helpers for worker onboarding."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import secrets
+from typing import Any
+
+
+class InviteCodeError(ValueError):
+    """Raised when an invite code cannot be decoded or validated."""
+
+
+def create_invite_code(
+    *,
+    broker_host: str,
+    broker_port: int,
+    room: str,
+    device_name: str,
+    tls: bool = False,
+) -> str:
+    payload = {
+        "broker": {
+            "host": _require_non_empty("broker.host", broker_host),
+            "port": _require_port(broker_port),
+        },
+        "room": _require_non_empty("room", room),
+        "device_name": _require_non_empty("device_name", device_name),
+        "token": secrets.token_urlsafe(32),
+        "tls": bool(tls),
+    }
+    raw = json.dumps(
+        payload,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    return base64.urlsafe_b64encode(raw).decode("ascii")
+
+
+def parse_invite_code(invite_code: str) -> dict[str, Any]:
+    try:
+        raw = base64.b64decode(
+            invite_code.encode("ascii"),
+            altchars=b"-_",
+            validate=True,
+        )
+    except (UnicodeEncodeError, binascii.Error) as exc:
+        raise InviteCodeError("invite code is not valid urlsafe base64") from exc
+
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise InviteCodeError("invite code does not contain valid JSON") from exc
+
+    return _normalize_payload(payload)
+
+
+def _normalize_payload(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise InviteCodeError("invite payload must be a JSON object")
+
+    broker = payload.get("broker")
+    if not isinstance(broker, dict):
+        raise InviteCodeError("invite payload must include broker.host and broker.port")
+
+    return {
+        "broker": {
+            "host": _require_string_field(broker, "host", "broker.host"),
+            "port": _require_int_field(broker, "port", "broker.port"),
+        },
+        "room": _require_string_field(payload, "room", "room"),
+        "device_name": _require_string_field(payload, "device_name", "device_name"),
+        "token": _require_string_field(payload, "token", "token"),
+        "tls": _require_bool_field(payload, "tls", "tls"),
+    }
+
+
+def _require_non_empty(name: str, value: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+    return value
+
+
+def _require_port(value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError("broker.port must be an integer")
+    if value < 1 or value > 65535:
+        raise ValueError("broker.port must be between 1 and 65535")
+    return value
+
+
+def _require_string_field(data: dict[str, Any], key: str, name: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value:
+        raise InviteCodeError(f"invite payload field {name} must be a non-empty string")
+    return value
+
+
+def _require_int_field(data: dict[str, Any], key: str, name: str) -> int:
+    value = data.get(key)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise InviteCodeError(f"invite payload field {name} must be an integer")
+    if value < 1 or value > 65535:
+        raise InviteCodeError(f"invite payload field {name} is outside the valid port range")
+    return value
+
+
+def _require_bool_field(data: dict[str, Any], key: str, name: str) -> bool:
+    value = data.get(key)
+    if not isinstance(value, bool):
+        raise InviteCodeError(f"invite payload field {name} must be a boolean")
+    return value

a2a_agent-0.1.0/src/a2a_agent/protocol.py

@@ -0,0 +1,101 @@
+"""Small A2A-compatible message models used by the MQTT transport."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Any, ClassVar
+
+
+JsonDict = dict[str, Any]
+VALID_TASK_STATUSES = {"pending", "accepted", "working", "completed", "failed"}
+
+
+@dataclass(frozen=True)
+class AgentCard:
+    name: str
+
+    def to_dict(self) -> JsonDict:
+        return {"name": self.name}
+
+    @classmethod
+    def from_dict(cls, data: JsonDict) -> "AgentCard":
+        return cls(name=str(data["name"]))
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, sort_keys=True)
+
+    @classmethod
+    def from_json(cls, payload: str | bytes) -> "AgentCard":
+        return cls.from_dict(json.loads(payload))
+
+
+@dataclass(frozen=True)
+class Message:
+    role: str
+    parts: list[JsonDict]
+
+    def to_dict(self) -> JsonDict:
+        return {
+            "role": self.role,
+            "parts": [dict(part) for part in self.parts],
+        }
+
+    @classmethod
+    def from_dict(cls, data: JsonDict) -> "Message":
+        return cls(
+            role=str(data["role"]),
+            parts=[dict(part) for part in data.get("parts", [])],
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, sort_keys=True)
+
+    @classmethod
+    def from_json(cls, payload: str | bytes) -> "Message":
+        return cls.from_dict(json.loads(payload))
+
+
+@dataclass(frozen=True)
+class Task:
+    id: str
+    from_: str
+    to: str
+    status: str
+    messages: list[Message]
+
+    valid_statuses: ClassVar[set[str]] = VALID_TASK_STATUSES
+
+    def __post_init__(self) -> None:
+        if self.status not in self.valid_statuses:
+            allowed = ", ".join(sorted(self.valid_statuses))
+            raise ValueError(f"status must be one of: {allowed}")
+
+    def to_dict(self) -> JsonDict:
+        return {
+            "id": self.id,
+            "from": self.from_,
+            "to": self.to,
+            "status": self.status,
+            "messages": [message.to_dict() for message in self.messages],
+        }
+
+    @classmethod
+    def from_dict(cls, data: JsonDict) -> "Task":
+        return cls(
+            id=str(data["id"]),
+            from_=str(data["from"]),
+            to=str(data["to"]),
+            status=str(data["status"]),
+            messages=[
+                Message.from_dict(message)
+                for message in data.get("messages", [])
+            ],
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, sort_keys=True)
+
+    @classmethod
+    def from_json(cls, payload: str | bytes) -> "Task":
+        return cls.from_dict(json.loads(payload))

a2a_agent-0.1.0/src/a2a_agent/topics.py

@@ -0,0 +1,60 @@
+"""MQTT topic helpers for the A2A namespace."""
+
+CONFIG_DEVICES = "a2a/{room}/config/devices"
+CONFIG_COMMANDER = "a2a/{room}/config/commander"
+AGENT_CARD = "a2a/{room}/agents/{device}/card"
+AGENT_STATUS = "a2a/{room}/agents/{device}/status"
+CMD_REQUEST = "a2a/{room}/cmd/{device}/request"
+CMD_RESPONSE = "a2a/{room}/cmd/{device}/response"
+CMD_TASK_STATUS = "a2a/{room}/cmd/{device}/task-status"
+
+
+def _segment(value: str, name: str) -> str:
+    if not value:
+        raise ValueError(f"{name} must not be empty")
+    if "/" in value:
+        raise ValueError(f"{name} must not contain '/'")
+    return value
+
+
+def config_devices_topic(room: str) -> str:
+    return CONFIG_DEVICES.format(room=_segment(room, "room"))
+
+
+def config_commander_topic(room: str) -> str:
+    return CONFIG_COMMANDER.format(room=_segment(room, "room"))
+
+
+def agent_card_topic(room: str, device: str) -> str:
+    return AGENT_CARD.format(
+        room=_segment(room, "room"),
+        device=_segment(device, "device"),
+    )
+
+
+def agent_status_topic(room: str, device: str) -> str:
+    return AGENT_STATUS.format(
+        room=_segment(room, "room"),
+        device=_segment(device, "device"),
+    )
+
+
+def cmd_request_topic(room: str, device: str) -> str:
+    return CMD_REQUEST.format(
+        room=_segment(room, "room"),
+        device=_segment(device, "device"),
+    )
+
+
+def cmd_response_topic(room: str, device: str) -> str:
+    return CMD_RESPONSE.format(
+        room=_segment(room, "room"),
+        device=_segment(device, "device"),
+    )
+
+
+def cmd_task_status_topic(room: str, device: str) -> str:
+    return CMD_TASK_STATUS.format(
+        room=_segment(room, "room"),
+        device=_segment(device, "device"),
+    )

a2a_agent-0.1.0/src/a2a_agent.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: a2a-agent
+Version: 0.1.0
+Summary: MQTT 위에서 도는 커맨더-워커 A2A 오케스트레이션 에이전트
+Author: Judvika
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt
+Requires-Dist: typer
+Requires-Dist: pyyaml
+Dynamic: license-file
+
+# a2a-agent
+
+`a2a-agent`는 MQTT 위에서 커맨더와 워커가 A2A 형식 메시지를 주고받기 위한 작은 명령줄 도구입니다.
+
+현재 `0.1.0`은 설정 파일 저장, 초대 코드 생성과 참여, 워커 역할 기록, 상태 확인을 지원합니다. 실제 작업 전송 명령인 `send`는 아직 자리 표시자입니다.
+
+## 설치
+
+PyPI 배포 후에는 다음처럼 설치할 수 있습니다.
+
+```bash
+python -m pip install a2a-agent
+```
+
+개발 환경에서 소스 코드로 설치하려면 저장소 루트에서 실행합니다.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+## 기본 사용
+
+커맨더 설정을 만듭니다.
+
+```bash
+a2a-agent init --room team --device-name commander --broker-host broker.example.com
+```
+
+워커 초대 코드를 만듭니다.
+
+```bash
+a2a-agent invite device-a
+```
+
+워커 기기에서는 초대 코드로 참여합니다.
+
+```bash
+a2a-agent join "초대코드"
+```
+
+커맨더에서 워커 역할을 기록합니다.
+
+```bash
+a2a-agent set-role device-a research "collect project context"
+```
+
+현재 설정을 확인합니다.
+
+```bash
+a2a-agent status
+```
+
+## 구조
+
+```text
+a2a-agent/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── src/a2a_agent/
+│   ├── cli.py
+│   ├── client.py
+│   ├── config.py
+│   ├── invite.py
+│   ├── protocol.py
+│   └── topics.py
+└── tests/
+```
+
+주요 모듈은 다음 역할을 맡습니다.
+
+- `cli.py`: 명령줄 진입점
+- `config.py`: 로컬 설정 파일 저장과 읽기
+- `invite.py`: 초대 코드 생성과 파싱
+- `protocol.py`: A2A 메시지 자료 구조
+- `topics.py`: MQTT 토픽 문자열 생성
+- `client.py`: `paho-mqtt` 래퍼
+
+## 라이선스
+
+MIT 라이선스를 따릅니다.

a2a_agent-0.1.0/src/a2a_agent.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/a2a_agent/__init__.py
+src/a2a_agent/cli.py
+src/a2a_agent/client.py
+src/a2a_agent/config.py
+src/a2a_agent/invite.py
+src/a2a_agent/protocol.py
+src/a2a_agent/topics.py
+src/a2a_agent.egg-info/PKG-INFO
+src/a2a_agent.egg-info/SOURCES.txt
+src/a2a_agent.egg-info/dependency_links.txt
+src/a2a_agent.egg-info/entry_points.txt
+src/a2a_agent.egg-info/requires.txt
+src/a2a_agent.egg-info/top_level.txt
+tests/test_client.py
+tests/test_config.py
+tests/test_invite.py
+tests/test_protocol.py
+tests/test_topics.py

a2a_agent-0.1.0/src/a2a_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

a2a_agent-0.1.0/src/a2a_agent.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+a2a-agent = a2a_agent.cli:app

a2a_agent-0.1.0/src/a2a_agent.egg-info/requires.txt

@@ -0,0 +1,3 @@
+paho-mqtt
+typer
+pyyaml

a2a_agent-0.1.0/src/a2a_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+a2a_agent

a2a_agent-0.1.0/tests/test_client.py

@@ -0,0 +1,20 @@
+import warnings
+
+import paho.mqtt.client as mqtt
+
+from a2a_agent.client import MqttClient
+
+
+def test_mqtt_client_import_and_creation_do_not_connect(monkeypatch) -> None:
+    def fail_connect(*args, **kwargs) -> None:
+        raise AssertionError("connect must not be called during client creation")
+
+    monkeypatch.setattr(mqtt.Client, "connect", fail_connect)
+
+    MqttClient()
+
+
+def test_mqtt_client_creation_has_no_deprecation_warning() -> None:
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+        MqttClient()

a2a_agent-0.1.0/tests/test_config.py

@@ -0,0 +1,56 @@
+import stat
+
+from a2a_agent.config import AgentConfig
+from a2a_agent.config import BrokerConfig
+from a2a_agent.config import DeviceRole
+from a2a_agent.config import load_config
+from a2a_agent.config import save_config
+
+
+def test_default_config_values(tmp_path) -> None:
+    config = load_config(tmp_path / "missing.yaml")
+
+    assert config.room == "default"
+    assert config.device_name
+    assert config.broker == BrokerConfig()
+    assert config.role == "worker"
+    assert config.token is None
+    assert config.devices == {}
+
+
+def test_save_load_round_trip_and_file_mode(tmp_path) -> None:
+    path = tmp_path / "config.yaml"
+    config = AgentConfig(
+        room="team",
+        device_name="commander",
+        broker=BrokerConfig(host="broker.example.com", port=8883, tls=True),
+        role="commander",
+        devices={
+            "device-b": DeviceRole(
+                role="research",
+                description="collect local context",
+            )
+        },
+    )
+
+    saved_path = save_config(config, path)
+    loaded = load_config(path)
+
+    assert saved_path == path
+    assert loaded == config
+    assert stat.S_IMODE(path.stat().st_mode) == 0o600
+
+
+def test_worker_token_is_saved(tmp_path) -> None:
+    path = tmp_path / "config.yaml"
+    config = AgentConfig(
+        room="team",
+        device_name="device-b",
+        broker=BrokerConfig(host="broker.example.com", port=1883, tls=False),
+        role="worker",
+        token="runtime-generated-token",
+    )
+
+    save_config(config, path)
+
+    assert load_config(path) == config

a2a_agent-0.1.0/tests/test_invite.py

@@ -0,0 +1,27 @@
+import pytest
+
+from a2a_agent.invite import InviteCodeError, create_invite_code, parse_invite_code
+
+
+def test_invite_round_trip() -> None:
+    code = create_invite_code(
+        broker_host="broker.example.com",
+        broker_port=8883,
+        room="team",
+        device_name="device-b",
+        tls=True,
+    )
+
+    payload = parse_invite_code(code)
+
+    assert payload["broker"] == {"host": "broker.example.com", "port": 8883}
+    assert payload["room"] == "team"
+    assert payload["device_name"] == "device-b"
+    assert payload["tls"] is True
+    assert isinstance(payload["token"], str)
+    assert payload["token"]
+
+
+def test_parse_invite_rejects_broken_code() -> None:
+    with pytest.raises(InviteCodeError, match="invite code"):
+        parse_invite_code("not-a-valid-code")

a2a_agent-0.1.0/tests/test_protocol.py

@@ -0,0 +1,44 @@
+import json
+
+import pytest
+
+from a2a_agent.protocol import AgentCard, Message, Task
+
+
+def test_task_round_trip_maps_from_key() -> None:
+    task = Task(
+        id="task-001",
+        from_="commander",
+        to="device-b",
+        status="pending",
+        messages=[
+            Message(
+                role="user",
+                parts=[{"type": "text", "text": "check project"}],
+            )
+        ],
+    )
+
+    payload = task.to_json()
+    raw = json.loads(payload)
+
+    assert raw["from"] == "commander"
+    assert "from_" not in raw
+    assert Task.from_json(payload) == task
+
+
+def test_agent_card_round_trip() -> None:
+    card = AgentCard(name="Device B")
+
+    assert AgentCard.from_json(card.to_json()) == card
+
+
+def test_task_rejects_unknown_status() -> None:
+    with pytest.raises(ValueError):
+        Task(
+            id="task-001",
+            from_="commander",
+            to="device-b",
+            status="unknown",
+            messages=[],
+        )

a2a_agent-0.1.0/tests/test_topics.py

@@ -0,0 +1,24 @@
+import pytest
+
+from a2a_agent import topics
+
+
+def test_topic_helpers_return_exact_strings() -> None:
+    room = "team"
+    device = "device-b"
+
+    assert topics.config_devices_topic(room) == "a2a/team/config/devices"
+    assert topics.config_commander_topic(room) == "a2a/team/config/commander"
+    assert topics.agent_card_topic(room, device) == "a2a/team/agents/device-b/card"
+    assert topics.agent_status_topic(room, device) == "a2a/team/agents/device-b/status"
+    assert topics.cmd_request_topic(room, device) == "a2a/team/cmd/device-b/request"
+    assert topics.cmd_response_topic(room, device) == "a2a/team/cmd/device-b/response"
+    assert topics.cmd_task_status_topic(room, device) == "a2a/team/cmd/device-b/task-status"
+
+
+def test_topic_helpers_reject_slash_segments() -> None:
+    with pytest.raises(ValueError):
+        topics.cmd_request_topic("team/dev", "device-b")
+
+    with pytest.raises(ValueError):
+        topics.cmd_request_topic("team", "device/b")