zchat-protocol 0.1.0__tar.gz

zchat_protocol-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

zchat_protocol-0.1.0/LICENSE

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

zchat_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: zchat-protocol
+Version: 0.1.0
+Summary: Protocol definitions for zchat multi-agent collaboration
+Project-URL: Homepage, https://github.com/ezagent42/zchat-protocol
+Project-URL: Repository, https://github.com/ezagent42/zchat-protocol
+Author: ezagent42
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11

zchat_protocol-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "zchat-protocol"
+version = "0.1.0"
+description = "Protocol definitions for zchat multi-agent collaboration"
+requires-python = ">=3.11"
+dependencies = []
+license = "MIT"
+authors = [{ name = "ezagent42" }]
+
+[project.urls]
+Homepage = "https://github.com/ezagent42/zchat-protocol"
+Repository = "https://github.com/ezagent42/zchat-protocol"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

zchat_protocol-0.1.0/tests/test_naming.py

@@ -0,0 +1,17 @@
+from zchat_protocol.naming import scoped_name, AGENT_SEPARATOR
+
+
+def test_separator_is_dash():
+    assert AGENT_SEPARATOR == "-"
+
+
+def test_scoped_name_adds_prefix():
+    assert scoped_name("helper", "alice") == "alice-helper"
+
+
+def test_scoped_name_no_double_prefix():
+    assert scoped_name("alice-helper", "alice") == "alice-helper"
+
+
+def test_scoped_name_different_prefix():
+    assert scoped_name("bob-helper", "alice") == "bob-helper"

zchat_protocol-0.1.0/tests/test_sys_messages.py

@@ -0,0 +1,37 @@
+from zchat_protocol.sys_messages import (
+    is_sys_message, make_sys_message,
+    encode_sys_for_irc, decode_sys_from_irc,
+    IRC_SYS_PREFIX,
+)
+
+
+def test_sys_prefix():
+    assert IRC_SYS_PREFIX == "__zchat_sys:"
+
+
+def test_make_sys_message_fields():
+    msg = make_sys_message("alice-agent0", "sys.stop_request", {"reason": "test"})
+    assert msg["nick"] == "alice-agent0"
+    assert msg["type"] == "sys.stop_request"
+    assert msg["body"]["reason"] == "test"
+    assert "id" in msg
+    assert "ts" in msg
+
+
+def test_is_sys_message():
+    assert is_sys_message({"type": "sys.stop_request"})
+    assert not is_sys_message({"type": "msg"})
+
+
+def test_irc_roundtrip():
+    msg = make_sys_message("alice-agent0", "sys.stop_request", {"reason": "test"})
+    encoded = encode_sys_for_irc(msg)
+    assert encoded.startswith("__zchat_sys:")
+    decoded = decode_sys_from_irc(encoded)
+    assert decoded["type"] == "sys.stop_request"
+    assert decoded["body"]["reason"] == "test"
+
+
+def test_decode_non_sys():
+    assert decode_sys_from_irc("hello world") is None
+    assert decode_sys_from_irc("{json-like}") is None

zchat_protocol-0.1.0/uv.lock

@@ -0,0 +1,79 @@
+version = 1
+revision = 3
+requires-python = ">=3.11"
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/65/ee/299d360cdc32edc7d2cf530f3accf79c4fca01e96ffc950d8a52213bd8e4/packaging-26.0.tar.gz", hash = "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", size = 143416, upload-time = "2026-01-21T20:50:39.064Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.19.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
+]
+
+[[package]]
+name = "zchat-protocol"
+version = "0.1.0"
+source = { editable = "." }
+
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+dev = [{ name = "pytest", specifier = ">=9.0.2" }]

zchat_protocol-0.1.0/zchat_protocol/__init__.py

@@ -0,0 +1,3 @@
+"""zchat protocol specification — authoritative definitions for naming, system messages, and commands."""
+
+PROTOCOL_VERSION = "0.1"

zchat_protocol-0.1.0/zchat_protocol/naming.py

@@ -0,0 +1,13 @@
+"""Agent naming conventions."""
+
+AGENT_SEPARATOR = "-"
+
+
+def scoped_name(name: str, username: str) -> str:
+    """Add username prefix to agent name if not already scoped.
+    'helper' + 'alice' → 'alice-helper'
+    'alice-helper' + 'alice' → 'alice-helper' (no change)
+    """
+    if AGENT_SEPARATOR in name:
+        return name
+    return f"{username}{AGENT_SEPARATOR}{name}"

zchat_protocol-0.1.0/zchat_protocol/sys_messages.py

@@ -0,0 +1,45 @@
+"""System message protocol for machine-to-machine control over IRC PRIVMSG."""
+
+from __future__ import annotations
+import json
+import os
+import time
+
+SYS_PREFIX = "sys."
+IRC_SYS_PREFIX = "__zchat_sys:"
+
+
+def _random_hex(n: int) -> str:
+    return os.urandom(n // 2 + 1).hex()[:n]
+
+
+def is_sys_message(msg: dict) -> bool:
+    """Check if a message is a system control message."""
+    return msg.get("type", "").startswith(SYS_PREFIX)
+
+
+def make_sys_message(nick: str, type: str, body: dict, ref_id: str | None = None) -> dict:
+    """Create a system message. Caller provides nick."""
+    return {
+        "id": _random_hex(8),
+        "nick": nick,
+        "type": type,
+        "body": body,
+        "ref_id": ref_id,
+        "ts": time.time(),
+    }
+
+
+def encode_sys_for_irc(msg: dict) -> str:
+    """Encode a sys message for IRC PRIVMSG transport."""
+    return f"{IRC_SYS_PREFIX}{json.dumps(msg)}"
+
+
+def decode_sys_from_irc(text: str) -> dict | None:
+    """Decode a sys message from IRC PRIVMSG. Returns None if not a sys message."""
+    if not text.startswith(IRC_SYS_PREFIX):
+        return None
+    try:
+        return json.loads(text[len(IRC_SYS_PREFIX):])
+    except json.JSONDecodeError:
+        return None