inter-agent-pi 0.2.0__py3-none-any.whl

inter_agent_pi/__init__.py

@@ -0,0 +1 @@
+"""Pi adapter package."""

inter_agent_pi/cli.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from inter_agent_pi import commands
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="inter-agent-pi")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    connect = sub.add_parser("connect")
+    connect.add_argument("name")
+    connect.add_argument("--label")
+
+    send = sub.add_parser("send")
+    send.add_argument("to")
+    send.add_argument("text")
+    send.add_argument("--from", dest="from_name")
+
+    broadcast = sub.add_parser("broadcast")
+    broadcast.add_argument("text")
+    broadcast.add_argument("--from", dest="from_name")
+
+    subscribe = sub.add_parser("subscribe")
+    subscribe.add_argument("channel")
+    subscribe.add_argument("--name", required=True)
+
+    unsubscribe = sub.add_parser("unsubscribe")
+    unsubscribe.add_argument("channel")
+    unsubscribe.add_argument("--name", required=True)
+
+    kick = sub.add_parser("kick")
+    kick.add_argument("name")
+
+    publish = sub.add_parser("publish")
+    publish.add_argument("channel")
+    publish.add_argument("text")
+    publish.add_argument("--from", dest="from_name")
+
+    channels = sub.add_parser("channels")
+    channels.add_argument("--json", action="store_true", help="emit JSON protocol output")
+
+    list_parser = sub.add_parser("list")
+    list_parser.add_argument("--json", action="store_true", help="emit JSON protocol output")
+
+    status = sub.add_parser("status")
+    status.add_argument("--json", action="store_true", help="emit JSON status output")
+
+    sub.add_parser("shutdown")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "connect":
+        return commands.connect(args.name, args.label)
+    if args.command == "send":
+        return commands.send(args.to, args.text, args.from_name)
+    if args.command == "broadcast":
+        return commands.broadcast(args.text, args.from_name)
+    if args.command == "subscribe":
+        return commands.subscribe(args.channel, args.name)
+    if args.command == "unsubscribe":
+        return commands.unsubscribe(args.channel, args.name)
+    if args.command == "kick":
+        return commands.kick(args.name)
+    if args.command == "publish":
+        return commands.publish(args.channel, args.text, args.from_name)
+    if args.command == "channels":
+        return commands.channels(as_json=args.json)
+    if args.command == "list":
+        return commands.list_sessions()
+    if args.command == "status":
+        print(commands.status_json())
+        return 0
+    if args.command == "shutdown":
+        return commands.shutdown()
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inter_agent_pi/commands.py

@@ -0,0 +1,348 @@
+"""Pi adapter wrappers around importable core command APIs.
+
+Core supports `list`; adapter surfaces may choose whether to expose it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+
+from inter_agent.core import adapter_control as control
+from inter_agent.core import channels as core_channels
+from inter_agent.core import kick as core_kick
+from inter_agent.core import list as core_list
+from inter_agent.core import publish as core_publish
+from inter_agent.core import send as core_send
+from inter_agent.core import shutdown as core_shutdown
+from inter_agent.core import status as core_status
+from inter_agent.core.send import SendResult
+from inter_agent.core.shared import Limits, resolve_endpoint, validate_channel_name
+from websockets.exceptions import WebSocketException
+
+from inter_agent_pi import listener
+
+
+def _system_exit_code(exc: SystemExit) -> int:
+    if isinstance(exc.code, int):
+        return exc.code
+    if exc.code is not None:
+        print(exc.code, file=sys.stderr)
+    return 1
+
+
+def _expected_error_code(exc: Exception) -> int:
+    print(f"inter-agent-pi: {exc}", file=sys.stderr)
+    return 1
+
+
+def _send_result_code(result: SendResult) -> int:
+    if result.error is not None:
+        print(
+            f"inter-agent-pi: delivery failed ({result.error.code}): {result.error.message}",
+            file=sys.stderr,
+        )
+        return 1
+    print(result.welcome)
+    return 0
+
+
+def connect(name: str, label: str | None = None) -> int:
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        return asyncio.run(
+            listener.run_listener(
+                endpoint.host,
+                endpoint.port,
+                name,
+                label,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+                tls_key_path=endpoint.tls_key_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+
+
+def send(to: str, text: str, from_name: str | None = None) -> int:
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        result = asyncio.run(
+            core_send.send_direct_message(
+                endpoint.host,
+                endpoint.port,
+                to,
+                text,
+                from_name,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+    return _send_result_code(result)
+
+
+def broadcast(text: str, from_name: str | None = None) -> int:
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        result = asyncio.run(
+            core_send.broadcast_message(
+                endpoint.host,
+                endpoint.port,
+                text,
+                from_name,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+    return _send_result_code(result)
+
+
+def _control_response_code(response: dict[str, object]) -> int:
+    op = response.get("op")
+    if op in ("subscribe_ok", "unsubscribe_ok"):
+        print(json.dumps(response, ensure_ascii=False))
+        return 0
+    if op == "error":
+        code = response.get("code", "PROTOCOL_ERROR")
+        message = response.get("message", "protocol error")
+        print(f"inter-agent-pi: ({code}): {message}", file=sys.stderr)
+        return 1
+    print(f"inter-agent-pi: unexpected response: {response}", file=sys.stderr)
+    return 1
+
+
+def _validate_channel_or_error(channel: str) -> bool:
+    if not validate_channel_name(channel, Limits().channel_name_max):
+        print(f"inter-agent-pi: invalid channel name: {channel!r}", file=sys.stderr)
+        return False
+    return True
+
+
+def subscribe(channel: str, name: str) -> int:
+    """Subscribe the named live listener to a channel."""
+    if not _validate_channel_or_error(channel):
+        return 1
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        response = asyncio.run(
+            control.request(
+                "pi",
+                endpoint.host,
+                endpoint.port,
+                name,
+                listener.pi_data_dir(),
+                "subscribe",
+                channel,
+            )
+        )
+    except (
+        SystemExit,
+        control.ControlError,
+        OSError,
+        TimeoutError,
+        ValueError,
+        WebSocketException,
+    ) as exc:
+        print(f"inter-agent-pi: {exc}", file=sys.stderr)
+        return 1
+    return _control_response_code(response)
+
+
+def unsubscribe(channel: str, name: str) -> int:
+    """Unsubscribe the named live listener from a channel."""
+    if not _validate_channel_or_error(channel):
+        return 1
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        response = asyncio.run(
+            control.request(
+                "pi",
+                endpoint.host,
+                endpoint.port,
+                name,
+                listener.pi_data_dir(),
+                "unsubscribe",
+                channel,
+            )
+        )
+    except (
+        SystemExit,
+        control.ControlError,
+        OSError,
+        TimeoutError,
+        ValueError,
+        WebSocketException,
+    ) as exc:
+        print(f"inter-agent-pi: {exc}", file=sys.stderr)
+        return 1
+    return _control_response_code(response)
+
+
+def publish(channel: str, text: str, from_name: str | None = None) -> int:
+    if not _validate_channel_or_error(channel):
+        return 1
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        result = asyncio.run(
+            core_publish.publish_to_channel(
+                endpoint.host,
+                endpoint.port,
+                channel,
+                text,
+                from_name,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+    # Pi publish success prints the welcome envelope, matching send/broadcast.
+    if result.error is not None:
+        print(
+            f"inter-agent-pi: publish failed ({result.error.code}): {result.error.message}",
+            file=sys.stderr,
+        )
+        return 1
+    print(result.welcome)
+    return 0
+
+
+def channels(as_json: bool = True) -> int:
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        result = asyncio.run(
+            core_channels.list_channels(
+                endpoint.host,
+                endpoint.port,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+    print(result.raw_response)
+    return 0 if result.response.get("op") == "channels_ok" else 1
+
+
+def list_sessions() -> int:
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        result = asyncio.run(
+            core_list.list_sessions(
+                endpoint.host,
+                endpoint.port,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+    print(result.raw_response)
+    return 0
+
+
+def kick(name: str) -> int:
+    """Force-disconnect a named agent role session through a control connection.
+
+    User-only: the host command surface invokes this; no model-callable tool
+    wraps it. It does not require the local Pi listener to be connected.
+    """
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        result = asyncio.run(
+            core_kick.kick_session(
+                endpoint.host,
+                endpoint.port,
+                name=name,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+    if result.response_payload.get("op") == "kick_ok":
+        print(result.response)
+        return 0
+    code = result.response_payload.get("code", "PROTOCOL_ERROR")
+    message = result.response_payload.get("message", "kick failed")
+    print(f"inter-agent-pi: ({code}): {message}", file=sys.stderr)
+    return 1
+
+
+def shutdown() -> int:
+    try:
+        endpoint = resolve_endpoint(allow_discovery=True)
+        result = asyncio.run(
+            core_shutdown.shutdown_server(
+                endpoint.host,
+                endpoint.port,
+                tls=endpoint.tls,
+                data_dir=endpoint.data_dir,
+                tls_cert_path=endpoint.tls_cert_path,
+            )
+        )
+    except SystemExit as exc:
+        return _system_exit_code(exc)
+    except (OSError, TimeoutError, ValueError, WebSocketException) as exc:
+        return _expected_error_code(exc)
+    print(result.response)
+    return 0 if result.response_payload.get("op") == "shutdown_ok" else 1
+
+
+def status() -> dict[str, object]:
+    command = core_status.command_status()
+    endpoint = resolve_endpoint(allow_discovery=True)
+    server = asyncio.run(core_status.check_resolved_server_status(endpoint))
+    return {
+        "state": server.state,
+        "host": server.host,
+        "port": server.port,
+        "configured_host": server.configured_host,
+        "configured_port": server.configured_port,
+        "scheme": server.scheme,
+        "tls": server.tls,
+        "tls_source": server.tls_source,
+        "tls_cert_path": server.tls_cert_path,
+        "tls_cert_source": server.tls_cert_source,
+        "host_source": server.host_source,
+        "port_source": server.port_source,
+        "data_dir": server.data_dir,
+        "data_dir_source": server.data_dir_source,
+        "config_path": server.config_path,
+        "hints": list(server.hints),
+        "server_reachable": server.reachable,
+        "message": server.message,
+        "core_list_supported": command.list_supported,
+        "adapter_list_exposed": True,
+    }
+
+
+def status_json() -> str:
+    return json.dumps(status())

inter_agent_pi/listener.py

@@ -0,0 +1,409 @@
+"""Long-running Pi listener with automatic reconnection.
+
+The Pi extension spawns this listener as a child process. It connects to the
+inter-agent bus as an agent session, prints server frames to stdout (one JSON
+object per line), and reconnects with bounded backoff when the connection
+drops. The server is auto-started if it is not running.
+
+The extension reads stdout frames: ``welcome`` marks the listener ready,
+``msg`` frames are delivered as notifications, and ``error`` frames indicate
+permanent connection rejections.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import random
+import socket
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+import websockets
+from inter_agent.core import adapter_control as control
+from inter_agent.core.client import AgentSession
+from inter_agent.core.shared import DEFAULT_HOST, DEFAULT_PORT, resolve_endpoint
+
+RECONNECT_BACKOFF_MIN_S = 0.5
+RECONNECT_BACKOFF_MAX_S = 4.0
+RECONNECT_JITTER_FRAC = 0.2
+RECONNECT_DEADLINE_S = 60.0
+AUTO_STARTED_SERVER_IDLE_TIMEOUT_S = 300
+
+# Terminal kick signal: a post-welcome KICKED error ends this listener process
+# without reconnecting. It is intentionally not part of _PERMANENT_ERROR_CODES
+# (which classify the first welcome-time frame); KICKED arrives after welcome.
+KICKED_ERROR_CODE = "KICKED"
+
+# Server error codes that won't resolve by reconnecting.
+_PERMANENT_ERROR_CODES = frozenset(
+    {
+        "AUTH_FAILED",
+        "BAD_LABEL",
+        "BAD_NAME",
+        "BAD_ROLE",
+        "BAD_SESSION",
+        "NAME_TAKEN",
+        "SESSION_TAKEN",
+        "TOO_MANY_CONNECTIONS",
+    }
+)
+
+log = logging.getLogger("inter-agent.pi.listener")
+
+
+def pi_data_dir() -> Path:
+    """Return the Pi adapter data directory under the core data dir."""
+    from inter_agent.core.shared import data_dir as core_data_dir
+
+    path = core_data_dir() / "pi-sessions"
+    path.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path, 0o700)
+    except OSError:
+        pass
+    return path
+
+
+def _control_socket_path(host: str, port: int, name: str) -> Path:
+    return control.control_socket_path("pi", host, port, name, pi_data_dir())
+
+
+class PermanentError(Exception):
+    """Raised when the server returns an error that reconnecting cannot resolve."""
+
+
+def endpoint_available(host: str, port: int) -> bool:
+    """Return True when the configured TCP endpoint accepts connections."""
+    try:
+        with socket.create_connection((host, port), timeout=0.2):
+            return True
+    except OSError:
+        return False
+
+
+def _print_frame(payload: str, output: TextIO) -> None:
+    """Emit a single JSON frame to stdout, flushed."""
+    output.write(payload + "\n")
+    output.flush()
+
+
+def _start_server(
+    host: str,
+    port: int,
+    *,
+    tls: bool = False,
+    tls_cert_path: str | None = None,
+    tls_key_path: str | None = None,
+) -> subprocess.Popen[bytes] | None:
+    """Start inter-agent-server as a child process with an explicit idle timeout."""
+    try:
+        args = [
+            sys.executable,
+            "-m",
+            "inter_agent.core.server",
+            "--host",
+            host,
+            "--port",
+            str(port),
+            "--idle-timeout",
+            str(AUTO_STARTED_SERVER_IDLE_TIMEOUT_S),
+        ]
+        if tls:
+            args.append("--tls")
+        else:
+            args.append("--no-tls")
+        if tls_cert_path:
+            args.extend(["--tls-cert", tls_cert_path])
+        if tls_key_path:
+            args.extend(["--tls-key", tls_key_path])
+        return subprocess.Popen(
+            args,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except OSError:
+        return None
+
+
+async def _connect_and_stream(
+    host: str,
+    port: int,
+    name: str,
+    label: str | None,
+    output: TextIO,
+    *,
+    tls: bool = False,
+    data_dir: Path | None = None,
+    tls_cert_path: Path | None = None,
+    desired_channels: set[str] | None = None,
+    control_path: Path | None = None,
+) -> None:
+    """Connect once, print raw frames, and return when the connection closes.
+
+    Reapplies the desired subscription set after a welcome so a transient
+    reconnect does not drop subscriptions. Raises PermanentError if the server
+    rejects the connection with a permanent error code as the first frame.
+    """
+    desired = desired_channels
+
+    async with AgentSession(
+        host, port, name, label, tls=tls, data_dir=data_dir, tls_cert_path=tls_cert_path
+    ) as session:
+        control_server: control.ControlServer | None = None
+
+        async def handle_request(op: str, channel: str) -> dict[str, object]:
+            try:
+                if op == "subscribe":
+                    response = await session.subscribe(channel)
+                    if response.get("op") == "subscribe_ok" and desired is not None:
+                        desired.add(channel)
+                    return response
+                response = await session.unsubscribe(channel)
+                if response.get("op") == "unsubscribe_ok" and desired is not None:
+                    desired.discard(channel)
+                return response
+            except Exception as exc:
+                return {"op": "error", "code": "LISTENER_UNAVAILABLE", "message": str(exc)}
+
+        async def reapply_desired() -> None:
+            for channel in sorted(desired or ()):
+                try:
+                    await session.subscribe(channel)
+                except Exception:
+                    pass
+
+        async def bind_control() -> None:
+            # (Re)bind the local control socket. Failures fail closed: the
+            # listener stays usable and the extension is told control is
+            # unavailable rather than rediscovering the connection down.
+            nonlocal control_server
+            if control_server is not None:
+                await control_server.stop()
+                control_server = None
+            if control_path is None:
+                return
+            try:
+                server = control.ControlServer(control_path, handle_request)
+                started = await server.start()
+                if not started:
+                    log.warning("control socket unavailable; subscribe/unsubscribe disabled")
+                    await server.stop()
+                    return
+                control_server = server
+            except OSError as exc:
+                log.warning("control socket setup failed: %s", exc)
+
+        try:
+            first = True
+            async for raw in session:
+                try:
+                    payload = json.loads(raw)
+                except json.JSONDecodeError:
+                    payload = None
+                op = payload.get("op") if payload is not None else None
+
+                if op == "welcome":
+                    # Reapply subscriptions and bind the control socket BEFORE
+                    # emitting the welcome so the host cannot mark the listener
+                    # ready before channels are restored and the bridge is
+                    # accepting requests.
+                    await reapply_desired()
+                    await bind_control()
+                    _print_frame(raw, output)
+                    first = False
+                    continue
+
+                if first:
+                    # The initial frame is part of readiness: emit it exactly
+                    # once before acting on it so the host sees the raw error.
+                    _print_frame(raw, output)
+                    first = False
+                    if op == "error":
+                        code = payload.get("code", "") if payload is not None else ""
+                        if isinstance(code, str) and code in _PERMANENT_ERROR_CODES:
+                            raise PermanentError(f"{code}: {payload.get('message', '')}")
+                        return
+                    continue
+                if (
+                    op == "error"
+                    and payload is not None
+                    and payload.get("code") == KICKED_ERROR_CODE
+                ):
+                    # Terminal kick: stop reconnecting for this listener process.
+                    # The routing name stays free for an explicit later reconnect.
+                    raise PermanentError(f"{KICKED_ERROR_CODE}: {payload.get('message', '')}")
+                if (
+                    op == "msg"
+                    and isinstance(payload.get("channel"), str)
+                    and payload.get("from_name") == name
+                ):
+                    continue
+                _print_frame(raw, output)
+        finally:
+            if control_server is not None:
+                await control_server.stop()
+                control_server = None
+
+
+def _jittered_delay(backoff: float) -> float:
+    jitter = backoff * RECONNECT_JITTER_FRAC
+    return max(0.0, backoff + random.uniform(-jitter, jitter))
+
+
+async def run_listener(
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    name: str = "",
+    label: str | None = None,
+    output: TextIO | None = None,
+    deadline_s: float = RECONNECT_DEADLINE_S,
+    *,
+    tls: bool = False,
+    data_dir: Path | None = None,
+    tls_cert_path: Path | None = None,
+    tls_key_path: Path | None = None,
+) -> int:
+    """Run the listener with automatic reconnection and eventual give-up.
+
+    Reconnects with bounded backoff while the connection is down. Gives up if
+    a reconnection would land at or past ``deadline_s`` seconds from the first
+    failure. Each successful connection resets the deadline, so a flapping
+    server that connects intermittently does not give up.
+
+    Returns 0 on clean shutdown, 1 on permanent error or give-up.
+    """
+    stream = output or sys.stdout
+    desired_channels: set[str] = set()
+    try:
+        control_path: Path | None = _control_socket_path(host, port, name)
+    except OSError:
+        log.warning("control socket unavailable; subscribe/unsubscribe disabled")
+        control_path = None
+    backoff = RECONNECT_BACKOFF_MIN_S
+    deadline: float | None = None
+    server_started = False
+
+    while True:
+        # Ensure the server is running, auto-starting if needed.
+        if not endpoint_available(host, port):
+            if not server_started:
+                proc = _start_server(
+                    host,
+                    port,
+                    tls=tls,
+                    tls_cert_path=str(tls_cert_path) if tls_cert_path is not None else None,
+                    tls_key_path=str(tls_key_path) if tls_key_path is not None else None,
+                )
+                if proc is None:
+                    print(
+                        "[inter-agent] failed to auto-start server; giving up",
+                        file=sys.stderr,
+                    )
+                    return 1
+                server_started = True
+                log.info("auto-started server pid %s", proc.pid)
+            # Wait for the server to come up.
+            ready = False
+            for _ in range(30):
+                if endpoint_available(host, port):
+                    ready = True
+                    break
+                await asyncio.sleep(0.5)
+            if not ready:
+                if deadline is None:
+                    deadline = asyncio.get_running_loop().time() + deadline_s
+                if asyncio.get_running_loop().time() >= deadline:
+                    print(
+                        "[inter-agent] server did not become available; giving up",
+                        file=sys.stderr,
+                    )
+                    return 1
+                await asyncio.sleep(_jittered_delay(backoff))
+                backoff = min(backoff * 2, RECONNECT_BACKOFF_MAX_S)
+                continue
+
+        try:
+            await _connect_and_stream(
+                host,
+                port,
+                name,
+                label,
+                stream,
+                tls=tls,
+                data_dir=data_dir,
+                tls_cert_path=tls_cert_path,
+                desired_channels=desired_channels,
+                control_path=control_path,
+            )
+            # Connection closed normally — reset and reconnect.
+            backoff = RECONNECT_BACKOFF_MIN_S
+            deadline = None
+        except PermanentError:
+            return 1
+        except (ConnectionRefusedError, OSError, websockets.ConnectionClosed):
+            pass
+
+        if deadline is None:
+            deadline = asyncio.get_running_loop().time() + deadline_s
+        if asyncio.get_running_loop().time() >= deadline:
+            print(
+                f"[inter-agent] giving up; could not reconnect within {deadline_s:.0f}s",
+                file=sys.stderr,
+            )
+            return 1
+
+        await asyncio.sleep(_jittered_delay(backoff))
+        backoff = min(backoff * 2, RECONNECT_BACKOFF_MAX_S)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="inter-agent-pi connect")
+    parser.add_argument("name", nargs="?")
+    parser.add_argument("--name", dest="name_option")
+    parser.add_argument("--label")
+    parser.add_argument("--host")
+    parser.add_argument("--port", type=int)
+    parser.add_argument("--tls", dest="tls", action="store_true", default=None)
+    parser.add_argument("--no-tls", dest="tls", action="store_false")
+    parser.add_argument("--tls-cert")
+    parser.add_argument("--tls-key")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    name = args.name_option or args.name
+    if not name:
+        parser.error("name is required")
+    endpoint = resolve_endpoint(
+        args.host,
+        args.port,
+        allow_discovery=True,
+        tls=args.tls,
+        tls_cert_path=args.tls_cert,
+        tls_key_path=args.tls_key,
+    )
+    return asyncio.run(
+        run_listener(
+            endpoint.host,
+            endpoint.port,
+            name,
+            args.label,
+            tls=endpoint.tls,
+            data_dir=endpoint.data_dir,
+            tls_cert_path=endpoint.tls_cert_path,
+            tls_key_path=endpoint.tls_key_path,
+        )
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inter_agent_pi-0.2.0.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: inter-agent-pi
+Version: 0.2.0
+Summary: Pi helper for the inter-agent message bus: connect listener and command-line tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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.md
+Requires-Dist: inter-agent-core==0.2.0
+Requires-Dist: websockets==16.0
+Dynamic: license-file
+
+# inter-agent-pi
+
+[![Pi](https://img.shields.io/badge/pi-extension-purple)](https://github.com/arcanemachine/inter-agent-pi)
+
+The Pi extension for the inter-agent message bus.
+
+It connects a Pi coding-agent session to the bus as a named agent,
+exposes grouped `/inter-agent` commands and a bounded set of agent-callable
+tools, delivers incoming peer messages as Pi notifications, and ships a Python
+helper (`inter-agent-pi` console command, `inter_agent_pi` import package) that
+wraps the importable [`inter-agent-core`](#runtime-dependency) listener and
+command APIs.
+
+This repository is an independent clean-history child. It contains no former
+monorepo history, no private workflow, no core runtime source, and no Claude
+Code material.
+
+## Installation (Pi extension)
+
+From a Pi session:
+
+```bash
+pi install npm:inter-agent-pi@0.2.0
+```
+
+Or install from a published Git tag (once published; do not pin a raw commit
+hash):
+
+```bash
+pi install https://github.com/arcanemachine/inter-agent-pi
+```
+
+Or load directly from a source checkout during development:
+
+```bash
+pi -e /path/to/inter-agent-pi/src/index.ts
+```
+
+The extension entry point is `./src/index.ts`.
+
+## Runtime dependency
+
+The helper depends on `inter-agent-core` `0.2.0` and on `websockets` `16.0`. A compatible `inter-agent-core` install
+must provide the `inter-agent-pi`, `inter-agent-server`, `inter-agent-connect`,
+`inter-agent-send`, `inter-agent-list`, `inter-agent-status`,
+`inter-agent-shutdown`, `inter-agent-kick`, `inter-agent-publish`, and
+`inter-agent-channels` console commands and the importable `inter_agent`
+namespace, including the promoted `inter_agent.core.adapter_control` bridge.
+
+> **Development note (non-release):** while the permanent `inter-agent-core`
+> repository is being prepared, the Python helper may be resolved against a
+> temporary local `inter-agent-core` candidate via a migration-only
+> `[tool.uv.sources]` path entry. That path source is removed and the lock is
+> re-resolved against the permanent `inter-agent-core` repository before any
+> publication. Never publish while the temporary path source remains.
+
+### Helper resolution precedence
+
+The extension resolves the Python runtime in this order:
+
+1. `INTER_AGENT_PI_HELPER` — an exact path to an `inter-agent-pi` executable;
+   its bin directory must also contain the required core helper scripts.
+2. An explicitly configured `interAgent.projectPath` — the helper is resolved
+   from that checkout's `.venv/bin`; if it is configured but incomplete the
+   extension fails fast with a bounded, actionable message.
+3. The extension-managed, documented runtime venv.
+4. `inter-agent-pi`, `inter-agent-connect`, and `inter-agent-server` discovered
+   together on `PATH`.
+5. A bounded setup-needed failure pointing back to this README.
+
+The legacy implicit fallback to `~/.local/share/inter-agent` is intentionally
+removed; that was a monorepo-era bootstrap assumption that no longer applies
+to the standalone package. Explicitly configured `interAgent.projectPath`
+remains supported for development.
+
+## Installing the Python helper
+
+From a source checkout:
+
+```bash
+uv sync --locked          # resolve inter-agent-core + dev/test tooling
+uv build                  # build wheel + sdist into dist/
+```
+
+Install the built wheel into a venv that already provides a compatible
+`inter-agent-core`, for example:
+
+```bash
+uv venv .venv
+uv pip install ./dist/*.whl <compatible-inter-agent-core-wheel>
+```
+
+The `inter-agent-pi` console command and the agent-callable tools all reuse
+this runtime.
+
+## Configuration
+
+Configuration is read from the Pi agent settings file under `interAgent.*`.
+Relative paths (`projectPath`, `dataDir`, TLS cert/key) resolve against the
+directory of the settings file.
+
+- `host` / `port` — override the default bus endpoint.
+- `dataDir` — shared bus state directory; defaults to the core default.
+- `secret` — shared secret for challenge-response auth; forwarded to helpers
+  as `INTER_AGENT_SECRET`. Do not store secrets in plaintext files in the repo.
+- `tls` / `tlsCert` / `tlsKey` — enable explicit TLS and point at a
+  certificate/key pair.
+
+Helper resolution precedence and the environment variables used by the helper
+match [`inter-agent-core`](#runtime-dependency). Helper install path, runtime
+state/config path, and bus state directories stay distinct so the bus identity
+does not fragment across installs.
+
+## Commands
+
+All commands ride the grouped `/inter-agent` command:
+
+```
+usage: /inter-agent <connect|disconnect|kick|rename|send|broadcast|publish|channels|subscribe|unsubscribe|list|status|delivery> [args]
+```
+
+- `/inter-agent connect <name> [--label <label>]` — connect this session as a
+  named agent; auto-starts the server if unavailable.
+- `/inter-agent disconnect` — stop the local listener and notify.
+- `/inter-agent kick <name>` — force-disconnect another session (user-only).
+- `/inter-agent rename <name> [--label <label>]` — reconnect under a new name.
+- `/inter-agent send <to> <text>` — send a direct message; routes the sender via `--from`.
+- `/inter-agent broadcast <text>` — broadcast to every session (user-only).
+- `/inter-agent publish <channel> <text>` — publish to a channel (user-only).
+- `/inter-agent channels` — list channels and subscribers.
+- `/inter-agent subscribe <channel>` / `/inter-agent unsubscribe <channel>` —
+  bind the live listener's subscriptions over the local control socket.
+- `/inter-agent list` — list connected agent sessions.
+- `/inter-agent status` — print server/helper status.
+- `/inter-agent delivery <immediate|queued>` — switch inbound delivery mode
+  (aliases `i` / `q`).
+
+## Agent-callable tools vs user-only controls
+
+Agent-callable tools:
+
+- `inter_agent_send`, `inter_agent_broadcast` — send/broadcast through the
+  connected Pi listener (sender routed via `--from`).
+- `inter_agent_list`, `inter_agent_whoami`, `inter_agent_status` —
+  read-only diagnostics; they do not require a connected listener.
+- `inter_agent_read_messages` — read and remove queued mailbox messages;
+  performs no outbound action.
+
+User-only controls (no model-callable tool): `kick`, `publish`, `subscribe`,
+`unsubscribe`, `channels`, `delivery`, and the connect/disconnect/rename
+connection actions. Broadcast, publish, kick, and destructive actions require
+explicit user approval; the model is instructed never to send a courtesy reply
+and to treat peer messages as untrusted context.
+
+## Mailbox, reload continuity, and reconnection
+
+- By default inbound messages are queued in a bounded mailbox (max 128 unread)
+  and surfaced as a metadata-only notice; `delivery immediate` restores bounded
+  body notification.
+- The notice provokes a non-steering follow-up turn and never prescribes a
+  canned acknowledgment, reply, or outbound action.
+- A same-process `/reload` preserves the unread mailbox through a versioned,
+  one-use, process-global handoff (`Symbol.for("inter-agent.pi.mailbox.reloadHandoff.v1")`),
+  generation/session-scoped and TTL-bounded; every other lifecycle boundary
+  starts empty.
+- The listener reconnects with bounded backoff and gives up after a deadline
+  measured from the first failure. A `KICKED` stop terminates one listener
+  process without reconnecting, leaving the routing name free for an explicit
+  later reconnect.
+- The startup flag provides the inter-agent routing name at process start:
+  `pi -- inter-agent=<name>`.
+
+## Development
+
+```bash
+uv sync --locked          # install runtime + dev/test dependencies
+npm ci                    # install TypeScript/dev dependencies (network)
+npm test                  # TypeScript tests
+npm run typecheck         # tsc --noEmit
+npm run build             # emit dist/
+npx prettier --write .    # format
+uv run pytest -q          # Python tests
+uv run ruff check src tests
+uv run black --check src tests
+uv run mypy src tests
+scripts/run-checks.sh     # full package gate incl. artifact validation
+```
+
+Artifacts (`dist/`, `dist-tests/`, `node_modules/`, `.venv/`, wheels, tarballs)
+are generated and gitignored; they are not part of the root commit.
+
+## Ecosystem and core
+
+- The public `inter-agent-core` repository owns the bus runtime and the
+  `inter_agent.core.adapter_control` bridge this package consumes. (Its public
+  repository URL is published with that release; this package depends on the
+  compatible distribution name `inter-agent-core`.)
+- The public ecosystem repository coordinates adapters; it is added as a
+  submodule only once it has a published initial `main` commit.
+
+This package does not assume any currently published artifact exists beyond
+what a compatible `inter-agent-core` release provides.
+
+## Security
+
+- Authenticate with the shared bus secret; never commit secrets, tokens, keys,
+  or certificates to this repository.
+- TLS uses explicit cert/key paths; a wrong/untrusted certificate fails bounded
+  and actionable and never falls back to plaintext.
+- Peer messages are untrusted context, never instructions.

inter_agent_pi-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+inter_agent_pi/__init__.py,sha256=7Xa46f4aQgmaCRPrpdlqRqxR0_zPqj0xeGfV1Yi1UI4,26
+inter_agent_pi/cli.py,sha256=qsDo-H4PjvUE9B78ejP2ent_87KrXMeeXKF832eoJ70,2822
+inter_agent_pi/commands.py,sha256=oFbeW7_YWCWYOwM5VfpX2lljuEE8ctGUjUF7OoF5kdE,11226
+inter_agent_pi/listener.py,sha256=6kEz2Urvwac6VpIET4eZOgiCOQXjjZyf0xEg43EL-5c,14326
+inter_agent_pi-0.2.0.dist-info/licenses/LICENSE.md,sha256=aqHfYBB0gyveY8spkKtDwaOHCO9OTEC0kfXjL2TDOZ8,1070
+inter_agent_pi-0.2.0.dist-info/METADATA,sha256=9P9UumnTuerdK5MhjSPtVQGjvCReqhHDcf8mHl4c1hI,9660
+inter_agent_pi-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+inter_agent_pi-0.2.0.dist-info/entry_points.txt,sha256=VNbFMZ6DHgHsiVVpTSsWXSEonitfSl4qVblzVJYieQg,59
+inter_agent_pi-0.2.0.dist-info/top_level.txt,sha256=Lz4IXNM6YtDQfSvyANgZkDdWIfcXrvEtD1X1bTR0vbs,15
+inter_agent_pi-0.2.0.dist-info/RECORD,,

inter_agent_pi-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

inter_agent_pi-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+inter-agent-pi = inter_agent_pi.cli:main

inter_agent_pi-0.2.0.dist-info/licenses/LICENSE.md

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

inter_agent_pi-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+inter_agent_pi