agentirc-cli 0.15.0__tar.gz → 0.15.1__tar.gz

{agentirc_cli-0.15.0 → agentirc_cli-0.15.1}/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/).
 
+## [0.15.1] - 2026-03-30
+
+
+### Fixed
+
+- Overview serve: flush stdout so port URL is visible when backgrounded
+- Overview serve: auto-kill previous instance for same server via PID/port files
+
 ## [0.15.0] - 2026-03-30
 
 

{agentirc_cli-0.15.0 → agentirc_cli-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 0.15.0
+Version: 0.15.1
 Summary: IRC protocol chatrooms for AI agents (and humans allowed)
 Project-URL: Homepage, https://github.com/OriNachum/agentirc
 Author: Ori Nachum

{agentirc_cli-0.15.0 → agentirc_cli-0.15.1}/agentirc/overview/renderer_web.py

@@ -1,14 +1,23 @@
 """Render mesh overview as HTML and serve via HTTP."""
 from __future__ import annotations
 
+import atexit
 import asyncio
 from http.server import HTTPServer, SimpleHTTPRequestHandler
+import os
 from pathlib import Path
+import signal
+import threading
+import time
 
 import re
 
 import mistune
 
+from agentirc.pidfile import (
+    is_process_alive, read_pid, read_port,
+    remove_pid, remove_port, write_pid, write_port,
+)
 from .collector import collect_mesh_state
 from .model import MeshState
 from .renderer_text import render_text
@@ -72,6 +81,45 @@ def render_html(
 </html>"""
 
 
+def _stop_existing_overview(pid_name: str) -> None:
+    """Kill a previous overview instance if running, clean up its files."""
+    existing_pid = read_pid(pid_name)
+    if existing_pid and is_process_alive(existing_pid):
+        existing_port = read_port(pid_name)
+        try:
+            os.kill(existing_pid, signal.SIGTERM)
+        except (PermissionError, ProcessLookupError) as exc:
+            remove_pid(pid_name)
+            remove_port(pid_name)
+            port_msg = f", port {existing_port}" if existing_port else ""
+            print(
+                f"Warning: could not stop previous overview (PID {existing_pid}"
+                f"{port_msg}): {exc}",
+                flush=True,
+            )
+            return
+        for _ in range(20):
+            if not is_process_alive(existing_pid):
+                break
+            time.sleep(0.1)
+        else:
+            try:
+                os.kill(existing_pid, signal.SIGKILL)
+            except (PermissionError, ProcessLookupError):
+                pass
+        remove_pid(pid_name)
+        remove_port(pid_name)
+        port_msg = f", port {existing_port}" if existing_port else ""
+        print(
+            f"Stopped previous overview for '{pid_name.removeprefix('overview-')}'"
+            f" (PID {existing_pid}{port_msg})",
+            flush=True,
+        )
+    elif existing_pid:
+        remove_pid(pid_name)
+        remove_port(pid_name)
+
+
 def serve_web(
     host: str,
     port: int,
@@ -84,6 +132,8 @@ def serve_web(
     serve_port: int = 0,
 ) -> None:
     """Start a local HTTP server serving the live overview."""
+    pid_name = f"overview-{server_name}"
+    _stop_existing_overview(pid_name)
 
     class OverviewHandler(SimpleHTTPRequestHandler):
         def do_GET(self):
@@ -110,11 +160,27 @@ def serve_web(
 
     httpd = HTTPServer(("127.0.0.1", serve_port), OverviewHandler)
     actual_port = httpd.server_address[1]
-    print(f"Overview dashboard: http://localhost:{actual_port}")
-    print("Press Ctrl+C to stop.")
+
+    write_pid(pid_name, os.getpid())
+    write_port(pid_name, actual_port)
+
+    def _cleanup():
+        remove_pid(pid_name)
+        remove_port(pid_name)
+
+    atexit.register(_cleanup)
+    if threading.current_thread() is threading.main_thread():
+        def _handle_term(_sig, _frame):
+            threading.Thread(target=httpd.shutdown, daemon=True).start()
+        signal.signal(signal.SIGTERM, _handle_term)
+
+    print(f"Overview dashboard: http://localhost:{actual_port}", flush=True)
+    print("Press Ctrl+C to stop.", flush=True)
     try:
         httpd.serve_forever()
     except KeyboardInterrupt:
-        print("\nStopped.")
+        print("\nStopped.", flush=True)
     finally:
         httpd.server_close()
+        _cleanup()
+        atexit.unregister(_cleanup)

agentirc_cli-0.15.1/agentirc/pidfile.py

@@ -0,0 +1,84 @@
+"""PID file management for agentirc daemon instances."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+PID_DIR = os.path.expanduser("~/.agentirc/pids")
+
+
+def _safe_name(name: str) -> str:
+    """Sanitize a daemon name to prevent path traversal."""
+    return re.sub(r"[^a-zA-Z0-9._-]", "_", Path(name).name)
+
+
+def write_pid(name: str, pid: int) -> Path:
+    """Write a PID file for the named daemon. Creates the directory if needed."""
+    pid_dir = Path(PID_DIR)
+    pid_dir.mkdir(parents=True, exist_ok=True)
+    pid_path = pid_dir / f"{_safe_name(name)}.pid"
+    pid_path.write_text(str(pid))
+    return pid_path
+
+
+def read_pid(name: str) -> int | None:
+    """Read the PID for the named daemon. Returns None if file is missing."""
+    pid_path = Path(PID_DIR) / f"{_safe_name(name)}.pid"
+    if not pid_path.exists():
+        return None
+    try:
+        return int(pid_path.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def remove_pid(name: str) -> None:
+    """Remove the PID file for the named daemon if it exists."""
+    pid_path = Path(PID_DIR) / f"{_safe_name(name)}.pid"
+    try:
+        pid_path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def write_port(name: str, port: int) -> Path:
+    """Write a port file for the named daemon. Creates the directory if needed."""
+    pid_dir = Path(PID_DIR)
+    pid_dir.mkdir(parents=True, exist_ok=True)
+    port_path = pid_dir / f"{_safe_name(name)}.port"
+    port_path.write_text(str(port))
+    return port_path
+
+
+def read_port(name: str) -> int | None:
+    """Read the port for the named daemon. Returns None if file is missing."""
+    port_path = Path(PID_DIR) / f"{_safe_name(name)}.port"
+    if not port_path.exists():
+        return None
+    try:
+        return int(port_path.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def remove_port(name: str) -> None:
+    """Remove the port file for the named daemon if it exists."""
+    port_path = Path(PID_DIR) / f"{_safe_name(name)}.port"
+    try:
+        port_path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def is_process_alive(pid: int) -> bool:
+    """Check whether a process with the given PID is alive."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        # Process exists but we don't have permission to signal it
+        return True

{agentirc_cli-0.15.0 → agentirc_cli-0.15.1}/docs/overview.md

@@ -48,6 +48,20 @@ memberships with roles, and cross-channel recent activity.
 styled HTML with the anthropic cream theme. Auto-refreshes at the interval
 set by `--refresh` (default: 5 seconds).
 
+### Instance Management
+
+Each overview server registers itself with a PID and port file in
+`~/.agentirc/pids/` (e.g., `overview-spark.pid`, `overview-spark.port`).
+
+- **One per server**: Starting a new overview for the same IRC server
+  auto-kills the previous instance via SIGTERM (with SIGKILL fallback).
+- **Multiple servers**: Different IRC servers can each have their own
+  overview site running simultaneously (keyed by `server_name`).
+- **Graceful shutdown**: SIGTERM and Ctrl+C both trigger clean shutdown
+  with PID/port file removal.
+- **Background visibility**: The dashboard URL is flushed to stdout
+  immediately, so it appears even when the process runs in the background.
+
 ## Data Sources
 
 - **IRC Observer**: Ephemeral connection queries LIST, NAMES, WHO, HISTORY

{agentirc_cli-0.15.0 → agentirc_cli-0.15.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "0.15.0"
+version = "0.15.1"
 description = "IRC protocol chatrooms for AI agents (and humans allowed)"
 readme = "README.md"
 license = "MIT"

agentirc_cli-0.15.1/tests/test_overview_web.py

@@ -0,0 +1,165 @@
+"""Tests for overview web renderer."""
+import os
+import threading
+import time
+
+from agentirc.overview.model import Agent, Message, MeshState, Room
+from agentirc.overview.renderer_web import render_html, serve_web, _stop_existing_overview
+from agentirc import pidfile
+
+
+def _make_fixture() -> MeshState:
+    now = time.time()
+    agent = Agent(
+        nick="spark-claude", status="active", activity="working on: tests",
+        channels=["#general"], server="spark",
+        backend="claude", model="claude-opus-4-6",
+    )
+    msg = Message(nick="spark-claude", text="hello", timestamp=now - 60, channel="#general")
+    room = Room(
+        name="#general", topic="Testing",
+        members=[agent], operators=["spark-claude"],
+        federation_servers=[], messages=[msg],
+    )
+    return MeshState(server_name="spark", rooms=[room], agents=[agent], federation_links=[])
+
+
+def test_render_html_produces_valid_html():
+    mesh = _make_fixture()
+    html = render_html(mesh, message_limit=4)
+    assert "<!DOCTYPE html>" in html
+    assert "<html" in html
+    assert "</html>" in html
+
+
+def test_render_html_contains_content():
+    mesh = _make_fixture()
+    html = render_html(mesh, message_limit=4)
+    assert "spark mesh" in html
+    assert "#general" in html
+    assert "spark-claude" in html
+    assert "hello" in html
+
+
+def test_render_html_has_cream_styles():
+    mesh = _make_fixture()
+    html = render_html(mesh, message_limit=4)
+    assert "#faf7f2" in html or "faf7f2" in html
+
+
+def test_render_html_has_auto_refresh():
+    mesh = _make_fixture()
+    html = render_html(mesh, message_limit=4, refresh_interval=5)
+    assert 'http-equiv="refresh"' in html or "refresh" in html.lower()
+
+
+def test_render_html_has_table_elements():
+    mesh = _make_fixture()
+    html = render_html(mesh, message_limit=4)
+    assert "<table" in html
+    assert "<th>" in html or "<th " in html
+    assert "status-active" in html
+
+
+# --- serve_web PID/port management tests ---
+
+
+def test_serve_web_writes_and_cleans_pid_port(tmp_path, monkeypatch):
+    """serve_web writes PID and port files, cleans up on shutdown."""
+    monkeypatch.setattr(pidfile, "PID_DIR", str(tmp_path))
+
+    pid_name = "overview-testserver"
+    pid_path = tmp_path / f"{pid_name}.pid"
+    port_path = tmp_path / f"{pid_name}.port"
+
+    # We need to stop the server after it starts. Patch HTTPServer to
+    # capture the instance so we can call shutdown() from a timer.
+    from http.server import HTTPServer
+    captured = {}
+    _orig_init = HTTPServer.__init__
+
+    def _patched_init(self, *args, **kwargs):
+        _orig_init(self, *args, **kwargs)
+        captured["httpd"] = self
+
+    monkeypatch.setattr(HTTPServer, "__init__", _patched_init)
+
+    def _run():
+        serve_web(
+            host="127.0.0.1", port=6667, server_name="testserver",
+            serve_port=0,
+        )
+
+    t = threading.Thread(target=_run, daemon=True)
+    t.start()
+
+    # Wait for PID file to appear
+    for _ in range(40):
+        if pid_path.exists() and port_path.exists():
+            break
+        time.sleep(0.05)
+
+    assert pid_path.exists(), "PID file should be created"
+    assert port_path.exists(), "Port file should be created"
+
+    stored_pid = int(pid_path.read_text().strip())
+    stored_port = int(port_path.read_text().strip())
+    assert stored_pid == os.getpid()
+    assert stored_port > 0
+
+    # Shut down the server gracefully
+    captured["httpd"].shutdown()
+    t.join(timeout=5)
+
+    assert not pid_path.exists(), "PID file should be cleaned up"
+    assert not port_path.exists(), "Port file should be cleaned up"
+
+
+def test_stop_existing_overview_kills_previous(tmp_path, monkeypatch):
+    """_stop_existing_overview sends SIGTERM to a live previous instance."""
+    monkeypatch.setattr(pidfile, "PID_DIR", str(tmp_path))
+
+    pid_name = "overview-testserver"
+    (tmp_path / f"{pid_name}.pid").write_text("99999")
+    (tmp_path / f"{pid_name}.port").write_text("12345")
+
+    # Simulate: process alive on first check, dead after SIGTERM
+    alive_calls = {"count": 0}
+
+    def _fake_alive(pid):
+        alive_calls["count"] += 1
+        return alive_calls["count"] == 1  # alive first, dead after
+
+    killed_pids = []
+    monkeypatch.setattr(os, "kill", lambda pid, sig: killed_pids.append((pid, sig)))
+
+    import agentirc.overview.renderer_web as rweb
+    monkeypatch.setattr(rweb, "is_process_alive", _fake_alive)
+
+    _stop_existing_overview(pid_name)
+
+    import signal
+    assert (99999, signal.SIGTERM) in killed_pids, "SIGTERM should be sent"
+    assert not (tmp_path / f"{pid_name}.pid").exists()
+    assert not (tmp_path / f"{pid_name}.port").exists()
+
+
+def test_stop_existing_overview_cleans_stale_pid(tmp_path, monkeypatch):
+    """Stale PID files (dead process) are cleaned without sending signals."""
+    monkeypatch.setattr(pidfile, "PID_DIR", str(tmp_path))
+
+    pid_name = "overview-stale"
+    (tmp_path / f"{pid_name}.pid").write_text("11111")
+    (tmp_path / f"{pid_name}.port").write_text("9999")
+
+    kills = []
+    monkeypatch.setattr(os, "kill", lambda pid, sig: kills.append((pid, sig)))
+
+    import agentirc.overview.renderer_web as rweb
+    monkeypatch.setattr(rweb, "is_process_alive", lambda pid: False)
+
+    _stop_existing_overview(pid_name)
+
+    assert not (tmp_path / f"{pid_name}.pid").exists()
+    assert not (tmp_path / f"{pid_name}.port").exists()
+    assert kills == [], "No signals should be sent for a dead process"

{agentirc_cli-0.15.0 → agentirc_cli-0.15.1}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.12"
 
 [[package]]
 name = "agentirc-cli"
-version = "0.15.0"
+version = "0.15.1"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },

agentirc_cli-0.15.0/agentirc/pidfile.py

@@ -1,49 +0,0 @@
-"""PID file management for agentirc daemon instances."""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-PID_DIR = os.path.expanduser("~/.agentirc/pids")
-
-
-def write_pid(name: str, pid: int) -> Path:
-    """Write a PID file for the named daemon. Creates the directory if needed."""
-    pid_dir = Path(PID_DIR)
-    pid_dir.mkdir(parents=True, exist_ok=True)
-    pid_path = pid_dir / f"{name}.pid"
-    pid_path.write_text(str(pid))
-    return pid_path
-
-
-def read_pid(name: str) -> int | None:
-    """Read the PID for the named daemon. Returns None if file is missing."""
-    pid_path = Path(PID_DIR) / f"{name}.pid"
-    if not pid_path.exists():
-        return None
-    try:
-        return int(pid_path.read_text().strip())
-    except (ValueError, OSError):
-        return None
-
-
-def remove_pid(name: str) -> None:
-    """Remove the PID file for the named daemon if it exists."""
-    pid_path = Path(PID_DIR) / f"{name}.pid"
-    try:
-        pid_path.unlink()
-    except FileNotFoundError:
-        pass
-
-
-def is_process_alive(pid: int) -> bool:
-    """Check whether a process with the given PID is alive."""
-    try:
-        os.kill(pid, 0)
-        return True
-    except ProcessLookupError:
-        return False
-    except PermissionError:
-        # Process exists but we don't have permission to signal it
-        return True

agentirc_cli-0.15.0/tests/test_overview_web.py

@@ -1,58 +0,0 @@
-"""Tests for overview web renderer."""
-import time
-
-from agentirc.overview.model import Agent, Message, MeshState, Room
-from agentirc.overview.renderer_web import render_html
-
-
-def _make_fixture() -> MeshState:
-    now = time.time()
-    agent = Agent(
-        nick="spark-claude", status="active", activity="working on: tests",
-        channels=["#general"], server="spark",
-        backend="claude", model="claude-opus-4-6",
-    )
-    msg = Message(nick="spark-claude", text="hello", timestamp=now - 60, channel="#general")
-    room = Room(
-        name="#general", topic="Testing",
-        members=[agent], operators=["spark-claude"],
-        federation_servers=[], messages=[msg],
-    )
-    return MeshState(server_name="spark", rooms=[room], agents=[agent], federation_links=[])
-
-
-def test_render_html_produces_valid_html():
-    mesh = _make_fixture()
-    html = render_html(mesh, message_limit=4)
-    assert "<!DOCTYPE html>" in html
-    assert "<html" in html
-    assert "</html>" in html
-
-
-def test_render_html_contains_content():
-    mesh = _make_fixture()
-    html = render_html(mesh, message_limit=4)
-    assert "spark mesh" in html
-    assert "#general" in html
-    assert "spark-claude" in html
-    assert "hello" in html
-
-
-def test_render_html_has_cream_styles():
-    mesh = _make_fixture()
-    html = render_html(mesh, message_limit=4)
-    assert "#faf7f2" in html or "faf7f2" in html
-
-
-def test_render_html_has_auto_refresh():
-    mesh = _make_fixture()
-    html = render_html(mesh, message_limit=4, refresh_interval=5)
-    assert 'http-equiv="refresh"' in html or "refresh" in html.lower()
-
-
-def test_render_html_has_table_elements():
-    mesh = _make_fixture()
-    html = render_html(mesh, message_limit=4)
-    assert "<table" in html
-    assert "<th>" in html or "<th " in html
-    assert "status-active" in html