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

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

@@ -4,6 +4,14 @@ 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
 
 

{agentirc_cli-3.0.1 → 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.1 → agentirc_cli-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 3.0.1
+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.1 → 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:

{agentirc_cli-3.0.1 → 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.1 → agentirc_cli-3.0.2}/pyproject.toml

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

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.1 → agentirc_cli-3.0.2}/uv.lock

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