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

agentirc_cli-0.15.2/.pr_agent.toml

@@ -0,0 +1,38 @@
+[pr_reviewer]
+extra_instructions = """
+## Project Context
+
+- The `packages/` directory is ONLY for the "assimilai" pattern (internal packages copied into other projects). Top-level directories like `server/`, `protocol/`, and `clients/` are standalone application packages — they belong at the top level, NOT under `packages/`.
+- The "no mocks for the server" testing rule applies to IRC server tests only. Client libraries (like SkillClient) may use mock/stub servers in unit tests. Integration tests in `test_integration_layer5.py` exercise the real server stack.
+- Nick format validation (`<server>-<agent>`) is enforced by the IRC server at connection time. Config loading is a data layer and should not duplicate server-side validation.
+- Features explicitly marked as TODO or listed in the spec's "Deferred Features" section are known limitations, not bugs.
+- The `clients/` directory contains agent client harnesses (daemons). It is NOT an internal package for assimilation.
+
+## Harness Conformance (CRITICAL)
+
+The authoritative spec is `docs/agent-harness-spec.md`. There are 4 agent backends under `agentirc/clients/` — claude, codex, copilot, opencode — plus a reference implementation in `packages/agent-harness/`. The all-backends rule: a feature that exists in only one backend is a bug.
+
+When reviewing changes to any file under `agentirc/clients/` or `packages/agent-harness/`, apply these checks:
+
+### Cross-backend propagation
+When a PR changes a file in `agentirc/clients/<backend>/`, check whether the same change must be applied to the other 3 backends. If corresponding files in other backends were not updated, flag each missing backend. Exception: `agent_runner.py` and `supervisor.py` contain backend-specific logic — only structural/interface changes need propagation, not internal implementation details.
+
+### Generic file identity
+These files MUST be identical across all 4 backends and `packages/agent-harness/`, except for import paths (`from agentirc.clients.<backend>.`): `irc_transport.py`, `message_buffer.py`, `socket_server.py`, `ipc.py`, `webhook.py`, `skill/irc_client.py`. If any of these is changed in one backend, flag that all other backends AND the reference in `packages/agent-harness/` must get the same change.
+
+### Interface contract
+If `agent_runner.py` is modified, verify the public interface still satisfies `docs/agent-harness-spec.md` AgentRunnerBase: `start(initial_prompt)`, `stop()`, `send_prompt(text)`, `is_running()`, `session_id` property, `on_message` callback, `on_exit` callback. If `supervisor.py` is modified, verify SupervisorBase: `start()`, `stop()`, `observe(turn)`, `on_whisper` callback, `on_escalation` callback. Flag any missing or renamed interface members.
+
+### Daemon contract
+If `daemon.py` is modified, verify all IPC dispatch handlers are still present: `irc_send`, `irc_read`, `irc_ask`, `irc_join`, `irc_part`, `irc_who`, `irc_channels`, `compact`, `clear`, `shutdown`. Also verify structural features (crash recovery, `_mention_targets`, sleep scheduler) are consistent across backends. If a structural feature is added to one daemon, flag its absence in the others.
+
+### Config schema
+If `config.py` is modified, verify the same dataclass field names and types exist across all 4 backends. Only default values may differ by backend (e.g., model names). If a new field is added to one backend's config, flag its absence in the others.
+
+### SKILL.md consistency
+If any `SKILL.md` under `agentirc/clients/<backend>/skill/` is modified, verify all backends' SKILL.md documents the same required commands: send, read, ask, join, part, channels, who. Flag format or content inconsistencies.
+
+### Spec-doc alignment
+If `docs/agent-harness-spec.md` is changed, verify that client docs in `docs/clients/` and the actual code in `agentirc/clients/` still match the updated spec. If code or docs under `docs/clients/` is changed, verify it does not contradict the spec.
+"""
+num_max_findings = 10

{agentirc_cli-0.15.0 → agentirc_cli-0.15.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/).
 
+## [0.15.2] - 2026-03-31
+
+
+### Changed
+
+- Extended .pr_agent.toml with harness conformance checks for cross-backend validation
+
+## [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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 0.15.0
+Version: 0.15.2
 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.2/agentirc/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version as _v
+
+__version__ = _v("agentirc-cli")

{agentirc_cli-0.15.0 → agentirc_cli-0.15.2}/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.2/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.2/docs/harness-conformance.md

@@ -0,0 +1,84 @@
+---
+title: "Harness Conformance"
+parent: "Agent Harness"
+nav_order: 8
+---
+
+# Harness Conformance Checks
+
+## Overview
+
+Qodo PR review is configured to enforce conformance across all 4 agent
+backends (claude, codex, copilot, opencode). When a PR touches files under
+`agentirc/clients/` or `packages/agent-harness/`, Qodo applies 7 checks
+that prevent backends from drifting apart.
+
+The authoritative spec is `docs/agent-harness-spec.md`.
+
+## Configuration
+
+All conformance rules live in `.pr_agent.toml` under the `[pr_reviewer]`
+section's `extra_instructions` field.
+
+## Checks
+
+### 1. Cross-backend propagation
+
+When a file in one backend changes, Qodo flags if the corresponding files
+in the other 3 backends were not updated. Exception: `agent_runner.py` and
+`supervisor.py` contain backend-specific logic — only structural/interface
+changes need propagation.
+
+### 2. Generic file identity
+
+These files must be identical across all backends and the reference in
+`packages/agent-harness/`, except for import paths:
+
+- `irc_transport.py`
+- `message_buffer.py`
+- `socket_server.py`
+- `ipc.py`
+- `webhook.py`
+- `skill/irc_client.py`
+
+### 3. Interface contract
+
+Changes to `agent_runner.py` or `supervisor.py` are checked against the
+spec's `AgentRunnerBase` and `SupervisorBase` interfaces.
+
+**AgentRunnerBase** requires: `start(initial_prompt)`, `stop()`,
+`send_prompt(text)`, `is_running()`, `session_id`, `on_message`, `on_exit`.
+
+**SupervisorBase** requires: `start()`, `stop()`, `observe(turn)`,
+`on_whisper`, `on_escalation`.
+
+### 4. Daemon contract
+
+Changes to `daemon.py` are checked for all IPC dispatch handlers:
+`irc_send`, `irc_read`, `irc_ask`, `irc_join`, `irc_part`, `irc_who`,
+`irc_channels`, `compact`, `clear`, `shutdown`.
+
+Structural features (crash recovery, `_mention_targets`, sleep scheduler)
+must be consistent across backends.
+
+### 5. Config schema
+
+Changes to `config.py` must preserve the same field names and types across
+all backends. Only default values (model names, agent identifiers) may
+differ.
+
+### 6. SKILL.md consistency
+
+All backends' `SKILL.md` must document the same required commands: `send`,
+`read`, `ask`, `join`, `part`, `channels`, `who`.
+
+### 7. Spec-doc alignment
+
+Changes to `docs/agent-harness-spec.md` are cross-referenced against
+client docs in `docs/clients/` and the code in `agentirc/clients/`.
+Changes to client docs or code are checked against the spec.
+
+## Adding New Checks
+
+Edit `.pr_agent.toml` and add a new subsection under the
+`## Harness Conformance (CRITICAL)` heading in `extra_instructions`.

{agentirc_cli-0.15.0 → agentirc_cli-0.15.2}/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