agentirc-cli 3.0.0__tar.gz → 3.0.2__tar.gz

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [3.0.2] - 2026-04-06
+
+
+### Fixed
+
+- Server startup readiness — culture server start now waits for port to accept connections before returning
+- Added startup phase logging to server log for diagnosing slow starts
+
+## [3.0.1] - 2026-04-06
+
+
+### Fixed
+
+- Fix empty error message when running `culture overview` against a starting or unreachable server
+
 ## [3.0.0] - 2026-04-06
 
 

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/CLAUDE.md

@@ -42,7 +42,7 @@ When implementing features, write a corresponding markdown doc in `docs/` descri
 
 ## Testing
 
-- `pytest` + `pytest-asyncio`
+- `pytest` + `pytest-asyncio`, always run with `-n auto` for parallel execution
 - No mocks for the server — tests spin up real server instances on random ports with real TCP connections
 - Validate each layer with real IRC clients (weechat/irssi)
 

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 3.0.0
+Version: 3.0.2
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/culture/cli.py

@@ -29,6 +29,7 @@ import logging
 import os
 import shutil
 import signal
+import socket
 import subprocess
 import sys
 import time
@@ -493,6 +494,39 @@ def _cmd_server(args: argparse.Namespace) -> None:
         print(f"Default server set to '{args.name}'")
 
 
+def _wait_for_port(
+    host: str,
+    port: int,
+    pid: int,
+    timeout: float = 30,
+) -> tuple[bool, str]:
+    """Poll *host*:*port* until a TCP connect succeeds or *timeout* expires.
+
+    Returns ``(True, "")`` on success, or ``(False, reason)`` on failure.
+    Checks that *pid* is still alive on every iteration so we fail fast if
+    the child crashes (e.g. because the port was already in use).
+    """
+    check_host = "127.0.0.1" if host == "0.0.0.0" else host
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not is_process_alive(pid):
+            return False, "failed to start"
+        try:
+            s = socket.create_connection((check_host, port), timeout=0.5)
+            s.close()
+        except OSError:
+            time.sleep(0.2)
+            continue
+        # Port responded — give the child a moment, then confirm it's
+        # still alive (guards against connecting to a *stale* listener
+        # on the same port while our child crashes).
+        time.sleep(0.1)
+        if not is_process_alive(pid):
+            return False, "failed to start"
+        return True, ""
+    return False, "started but not yet accepting connections"
+
+
 def _server_start(args: argparse.Namespace) -> None:
     pid_name = f"server-{args.name}"
 
@@ -532,19 +566,33 @@ def _server_start(args: argparse.Namespace) -> None:
     # Fork to daemonize
     pid = os.fork()
     if pid > 0:
-        time.sleep(0.2)
-        if is_process_alive(pid):
-            print(f"Server '{args.name}' started (PID {pid})")
-            print(f"  Listening on {args.host}:{args.port}")
-            print(f"  Logs: {LOG_DIR}/server-{args.name}.log")
-            # Auto-set default server if none is set
-            from culture.pidfile import read_default_server, write_default_server
-
-            if read_default_server() is None:
-                write_default_server(args.name)
+        log_hint = f"{LOG_DIR}/server-{args.name}.log"
+
+        if args.port == 0:
+            # Ephemeral port — can't probe; fall back to process-alive check
+            time.sleep(0.5)
+            if not is_process_alive(pid):
+                print(f"Server '{args.name}' failed to start", file=sys.stderr)
+                print(f"  Check logs: {log_hint}", file=sys.stderr)
+                sys.exit(1)
         else:
-            print(f"Server '{args.name}' failed to start", file=sys.stderr)
-            sys.exit(1)
+            ok, err = _wait_for_port(args.host, args.port, pid, timeout=30)
+            if not ok:
+                print(
+                    f"Server '{args.name}' {err}",
+                    file=sys.stderr,
+                )
+                print(f"  Check logs: {log_hint}", file=sys.stderr)
+                sys.exit(1)
+
+        print(f"Server '{args.name}' started (PID {pid})")
+        print(f"  Listening on {args.host}:{args.port}")
+        print(f"  Logs: {log_hint}")
+        # Auto-set default server if none is set
+        from culture.pidfile import read_default_server, write_default_server
+
+        if read_default_server() is None:
+            write_default_server(args.name)
         return
 
     # Child: detach from parent session
@@ -562,6 +610,13 @@ def _server_start(args: argparse.Namespace) -> None:
     os.dup2(devnull, 0)
     os.close(devnull)
 
+    # Reconfigure logging so handlers write to the redirected stderr (log file)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+        force=True,
+    )
+
     write_pid(pid_name, os.getpid())
 
     try:
@@ -1593,14 +1648,31 @@ def _cmd_overview(args: argparse.Namespace) -> None:
         )
         return
 
-    mesh = asyncio.run(
-        collect_mesh_state(
-            host=config.server.host,
-            port=config.server.port,
-            server_name=config.server.name,
-            message_limit=message_limit,
+    host, port = config.server.host, config.server.port
+    try:
+        mesh = asyncio.run(
+            collect_mesh_state(
+                host=host,
+                port=port,
+                server_name=config.server.name,
+                message_limit=message_limit,
+            )
         )
-    )
+    except ConnectionRefusedError:
+        print(
+            f"Error: could not connect to {host}:{port} — is the server running?",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except TimeoutError:
+        print(
+            f"Error: server at {host}:{port} not responding" " — it may still be starting up",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except OSError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
     output = render_text(
         mesh,
         room_filter=args.room,

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/culture/overview/collector.py

@@ -116,28 +116,35 @@ async def _connect(
         timeout=REGISTER_TIMEOUT,
     )
     nick = _temp_nick(server_name)
-    writer.write(f"NICK {nick}\r\nUSER overview 0 * :overview\r\n".encode())
-    await writer.drain()
+    try:
+        writer.write(f"NICK {nick}\r\nUSER overview 0 * :overview\r\n".encode())
+        await writer.drain()
 
-    deadline = asyncio.get_event_loop().time() + REGISTER_TIMEOUT
-    while True:
-        remaining = deadline - asyncio.get_event_loop().time()
-        if remaining <= 0:
-            raise TimeoutError("Registration timed out")
-        data = await asyncio.wait_for(reader.readline(), timeout=remaining)
-        line = data.decode().strip()
-        if not line:
-            continue
-        msg = IRCMessage.parse(line)
-        if msg.command == "PING":
-            writer.write(f"PONG :{msg.params[0]}\r\n".encode())
-            await writer.drain()
-        elif msg.command == "001":
-            return reader, writer, nick
-        elif msg.command == "433":
-            nick = _temp_nick(server_name)
-            writer.write(f"NICK {nick}\r\n".encode())
-            await writer.drain()
+        deadline = asyncio.get_event_loop().time() + REGISTER_TIMEOUT
+        while True:
+            remaining = deadline - asyncio.get_event_loop().time()
+            if remaining <= 0:
+                raise TimeoutError("Registration timed out")
+            try:
+                data = await asyncio.wait_for(reader.readline(), timeout=remaining)
+            except asyncio.TimeoutError:
+                raise TimeoutError("Registration timed out") from None
+            line = data.decode().strip()
+            if not line:
+                continue
+            msg = IRCMessage.parse(line)
+            if msg.command == "PING":
+                writer.write(f"PONG :{msg.params[0]}\r\n".encode())
+                await writer.drain()
+            elif msg.command == "001":
+                return reader, writer, nick
+            elif msg.command == "433":
+                nick = _temp_nick(server_name)
+                writer.write(f"NICK {nick}\r\n".encode())
+                await writer.drain()
+    except BaseException:
+        await _disconnect(writer)
+        raise
 
 
 async def _disconnect(writer: asyncio.StreamWriter) -> None:

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/culture/server/ircd.py

@@ -10,6 +10,8 @@ from culture.server.channel import Channel
 from culture.server.config import ServerConfig
 from culture.server.skill import Event, Skill
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from culture.bots.virtual_client import VirtualClient
     from culture.server.client import Client
@@ -41,16 +43,25 @@ class IRCd:
         self.bot_manager = None  # set in start() if webhook_port configured
 
     async def start(self) -> None:
+        logger.info("Registering default skills...")
         await self._register_default_skills()
+
+        logger.info("Restoring persistent rooms...")
         self._restore_persistent_rooms()
 
         # Initialize bot manager and webhook HTTP listener
         from culture.bots.bot_manager import BotManager
         from culture.bots.http_listener import HttpListener
 
+        logger.info("Loading bots...")
         self.bot_manager = BotManager(self)
         await self.bot_manager.load_bots()
 
+        logger.info(
+            "Binding IRC socket on %s:%d...",
+            self.config.host,
+            self.config.port,
+        )
         self._server = await asyncio.start_server(
             self._handle_connection,
             self.config.host,
@@ -63,16 +74,22 @@ class IRCd:
             self.config.webhook_port,
         )
         try:
+            logger.info(
+                "Starting webhook listener on port %d...",
+                self.config.webhook_port,
+            )
             await self._http_listener.start()
         except OSError:
             # Port unavailable (e.g. in tests using port 0 that got
             # assigned an in-use ephemeral port). Non-fatal — bots
             # still work, just without the HTTP endpoint.
-            logging.getLogger(__name__).warning(
+            logger.warning(
                 "Could not start webhook listener on port %d",
                 self.config.webhook_port,
             )
 
+        logger.info("Server ready")
+
     async def _register_default_skills(self) -> None:
         from culture.server.skills.history import HistorySkill
         from culture.server.skills.icon import IconSkill
@@ -101,9 +118,7 @@ class IRCd:
             try:
                 await skill.on_event(event)
             except Exception:
-                logging.getLogger(__name__).exception(
-                    "Skill %s failed on event %s", skill.name, event.type
-                )
+                logger.exception("Skill %s failed on event %s", skill.name, event.type)
 
         # Relay to linked peers — only relay locally-originated events
         # (no mesh routing; scope is direct peers only)
@@ -112,7 +127,7 @@ class IRCd:
                 try:
                     await link.relay_event(event)
                 except Exception:
-                    logging.getLogger(__name__).exception("Failed to relay event to %s", peer_name)
+                    logger.exception("Failed to relay event to %s", peer_name)
 
     def get_skill_for_command(self, command: str) -> Skill | None:
         for skill in self.skills:
@@ -190,7 +205,6 @@ class IRCd:
 
     async def _retry_link_loop(self, peer_name: str, link_config, state: dict) -> None:
         """Retry connecting to a peer with exponential backoff."""
-        logger = logging.getLogger(__name__)
         try:
             while True:
                 await asyncio.sleep(state["delay"])

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "3.0.0"
+version = "3.0.2"
 description = "Legacy alias for culture — install culture instead"
 readme = "README.md"
 license = "MIT"

agentirc_cli-3.0.2/tests/test_overview_cli.py

@@ -0,0 +1,133 @@
+"""Tests for overview CLI subcommand argument parsing and error handling."""
+
+import subprocess
+import sys
+from unittest.mock import patch
+
+import pytest
+
+
+def test_overview_help():
+    """The overview subcommand is registered and has help."""
+    result = subprocess.run(
+        [sys.executable, "-m", "culture", "overview", "--help"],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0
+    assert "--room" in result.stdout
+    assert "--agent" in result.stdout
+    assert "--messages" in result.stdout
+    assert "--serve" in result.stdout
+    assert "--refresh" in result.stdout
+
+
+def test_overview_default_args():
+    """Default args parse correctly."""
+    from culture.cli import _build_parser
+
+    parser = _build_parser()
+    args = parser.parse_args(["overview"])
+    assert args.command == "overview"
+    assert args.room is None
+    assert args.agent is None
+    assert args.messages == 4
+    assert args.serve is False
+    assert args.refresh == 5
+
+
+def test_overview_with_flags():
+    from culture.cli import _build_parser
+
+    parser = _build_parser()
+    args = parser.parse_args(["overview", "--room", "#general", "--messages", "10"])
+    assert args.room == "#general"
+    assert args.messages == 10
+
+
+def test_overview_connection_refused(capsys):
+    """ConnectionRefusedError produces a helpful message."""
+    from culture.cli import _build_parser, _cmd_overview
+
+    parser = _build_parser()
+    args = parser.parse_args(["overview"])
+
+    with patch(
+        "culture.overview.collector.collect_mesh_state",
+        side_effect=ConnectionRefusedError(111, "Connection refused"),
+    ):
+        with pytest.raises(SystemExit, match="1"):
+            _cmd_overview(args)
+
+    captured = capsys.readouterr()
+    assert "is the server running?" in captured.err
+
+
+def test_overview_timeout(capsys):
+    """TimeoutError produces a helpful message."""
+    from culture.cli import _build_parser, _cmd_overview
+
+    parser = _build_parser()
+    args = parser.parse_args(["overview"])
+
+    with patch(
+        "culture.overview.collector.collect_mesh_state",
+        side_effect=TimeoutError("Registration timed out"),
+    ):
+        with pytest.raises(SystemExit, match="1"):
+            _cmd_overview(args)
+
+    captured = capsys.readouterr()
+    assert "not responding" in captured.err
+    assert "still be starting up" in captured.err
+
+
+def test_overview_os_error(capsys):
+    """OSError shows the original error details."""
+    from culture.cli import _build_parser, _cmd_overview
+
+    parser = _build_parser()
+    args = parser.parse_args(["overview"])
+
+    with patch(
+        "culture.overview.collector.collect_mesh_state",
+        side_effect=OSError("Name or service not known"),
+    ):
+        with pytest.raises(SystemExit, match="1"):
+            _cmd_overview(args)
+
+    captured = capsys.readouterr()
+    assert "Name or service not known" in captured.err
+
+
+@pytest.mark.asyncio
+async def test_connect_timeout_has_message():
+    """_connect raises TimeoutError with a non-empty message on registration timeout."""
+    import asyncio
+
+    from culture.overview.collector import _connect
+
+    # TCP server that accepts but never sends IRC 001 (silent handshake)
+    stop = asyncio.Event()
+
+    async def hold_open(reader, writer):
+        await stop.wait()
+        writer.close()
+
+    server = await asyncio.start_server(hold_open, "127.0.0.1", 0)
+    port = server.sockets[0].getsockname()[1]
+
+    try:
+        with pytest.raises(TimeoutError, match="Registration timed out"):
+            import culture.overview.collector as col
+
+            original = col.REGISTER_TIMEOUT
+            col.REGISTER_TIMEOUT = 0.5
+            try:
+                await _connect("127.0.0.1", port, "test")
+            finally:
+                col.REGISTER_TIMEOUT = original
+    finally:
+        stop.set()
+        server.close()
+        await server.wait_closed()

agentirc_cli-3.0.2/tests/test_wait_for_port.py

@@ -0,0 +1,89 @@
+"""Tests for the _wait_for_port readiness helper."""
+
+from __future__ import annotations
+
+import socket
+import threading
+import time
+
+from culture.cli import _wait_for_port
+
+
+def _start_listener(port_holder: list, delay: float = 0) -> socket.socket:
+    """Start a TCP listener, optionally after *delay* seconds.
+
+    Stores the assigned port in *port_holder[0]*.
+    """
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+    def _bind():
+        if delay:
+            time.sleep(delay)
+        srv.bind(("127.0.0.1", 0))
+        srv.listen(1)
+        port_holder.append(srv.getsockname()[1])
+
+    t = threading.Thread(target=_bind, daemon=True)
+    t.start()
+    t.join(timeout=delay + 2)
+    return srv
+
+
+def test_success_immediate():
+    """Port already open — should return immediately."""
+    port_holder: list[int] = []
+    srv = _start_listener(port_holder)
+    try:
+        ok, err = _wait_for_port(
+            "127.0.0.1",
+            port_holder[0],
+            # Use our own PID (always alive)
+            pid=threading.current_thread().native_id or 1,
+            timeout=5,
+        )
+        assert ok
+        assert err == ""
+    finally:
+        srv.close()
+
+
+def test_timeout_no_listener():
+    """No listener — should time out."""
+    # Bind then close to get a free port that nothing listens on
+    tmp = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    tmp.bind(("127.0.0.1", 0))
+    port = tmp.getsockname()[1]
+    tmp.close()
+
+    import os
+
+    ok, err = _wait_for_port("127.0.0.1", port, pid=os.getpid(), timeout=1)
+    assert not ok
+    assert "not yet accepting connections" in err
+
+
+def test_process_dies():
+    """Dead PID — should fail fast."""
+    import subprocess
+
+    # Spawn a process that exits immediately to get a dead PID
+    p = subprocess.Popen(["true"])
+    p.wait()
+
+    ok, err = _wait_for_port("127.0.0.1", 1, pid=p.pid, timeout=5)
+    assert not ok
+    assert "failed to start" in err
+
+
+def test_host_0000_uses_localhost():
+    """0.0.0.0 host should probe 127.0.0.1."""
+    port_holder: list[int] = []
+    srv = _start_listener(port_holder)
+    try:
+        import os
+
+        ok, _ = _wait_for_port("0.0.0.0", port_holder[0], pid=os.getpid(), timeout=5)
+        assert ok
+    finally:
+        srv.close()

{agentirc_cli-3.0.0 → agentirc_cli-3.0.2}/uv.lock

@@ -561,7 +561,7 @@ wheels = [
 
 [[package]]
 name = "culture"
-version = "3.0.0"
+version = "3.0.2"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

agentirc_cli-3.0.0/tests/test_overview_cli.py

@@ -1,42 +0,0 @@
-"""Tests for overview CLI subcommand argument parsing."""
-
-import subprocess
-import sys
-
-
-def test_overview_help():
-    """The overview subcommand is registered and has help."""
-    result = subprocess.run(
-        [sys.executable, "-m", "culture", "overview", "--help"],
-        capture_output=True,
-        text=True,
-    )
-    assert result.returncode == 0
-    assert "--room" in result.stdout
-    assert "--agent" in result.stdout
-    assert "--messages" in result.stdout
-    assert "--serve" in result.stdout
-    assert "--refresh" in result.stdout
-
-
-def test_overview_default_args():
-    """Default args parse correctly."""
-    from culture.cli import _build_parser
-
-    parser = _build_parser()
-    args = parser.parse_args(["overview"])
-    assert args.command == "overview"
-    assert args.room is None
-    assert args.agent is None
-    assert args.messages == 4
-    assert args.serve is False
-    assert args.refresh == 5
-
-
-def test_overview_with_flags():
-    from culture.cli import _build_parser
-
-    parser = _build_parser()
-    args = parser.parse_args(["overview", "--room", "#general", "--messages", "10"])
-    assert args.room == "#general"
-    assert args.messages == 10