agentirc-cli 5.0.1__tar.gz → 5.0.3__tar.gz

{agentirc_cli-5.0.1 → agentirc_cli-5.0.3}/.claude/skills/pr-review/SKILL.md

@@ -179,8 +179,7 @@ Report completion back to the IRC channel:
 
 ```bash
 # Using the IRC skill
-CULTURE_NICK=<your-nick> python3 -m culture.clients.claude.skill.irc_client \
-  send "#general" "PR #<N> — all review threads addressed and resolved. Ready for merge."
+CULTURE_NICK="<agent-nick>" culture channel message "#general" "PR #<N> — all review threads addressed and resolved. Ready for merge."
 ```
 
 ## Script reference

{agentirc_cli-5.0.1 → agentirc_cli-5.0.3}/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [5.0.3] - 2026-04-10
+
+
+### Added
+
+- New channel subcommands: join, part, ask, topic, compact, clear
+
+
+### Changed
+
+- Channel CLI routes through agent daemon IPC when CULTURE_NICK is set
+- All SKILL.md files and learn prompt use culture channel CLI instead of python3 -m
+- Mesh update readiness probe verifies PID-based server identity
+
+
+### Fixed
+
+- culture channel message sends as agent nick instead of temporary peek nick (#203)
+- IRC skill references culture channel CLI instead of broken python3 -m path (#202)
+
+## [5.0.2] - 2026-04-09
+
+
+### Fixed
+
+- Handle missing credential tool (secret-tool/security/powershell) gracefully instead of crashing the server
+- Report restart failures in mesh update instead of claiming success
+
 ## [5.0.1] - 2026-04-09
 
 

{agentirc_cli-5.0.1 → agentirc_cli-5.0.3}/CLAUDE.md

@@ -59,6 +59,7 @@ When implementing features, write a corresponding markdown doc in `docs/` descri
 
 ## Testing
 
+- Use `/run-tests` to run the test suite (parallel + verbose by default)
 - `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-5.0.1 → agentirc_cli-5.0.3}/PKG-INFO

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

agentirc_cli-5.0.3/culture/cli/channel.py

@@ -0,0 +1,336 @@
+"""Channel subcommands: culture channel {list,read,message,who,join,part,ask,topic,compact,clear}."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+
+from .shared.constants import _CONFIG_HELP, DEFAULT_CONFIG
+from .shared.ipc import agent_socket_path, get_observer, ipc_request
+
+NAME = "channel"
+
+_ALL_CMDS = "list|read|message|who|join|part|ask|topic|compact|clear"
+_CHANNEL_HELP = "Channel (e.g. #general)"
+
+
+def _valid_nick(nick: str) -> bool:
+    """Check nick matches the required <server>-<agent> format."""
+    parts = nick.split("-", 1)
+    return len(parts) == 2 and all(parts)
+
+
+def _try_ipc(msg_type: str, **kwargs) -> dict | None:
+    """Try to route a command through the agent daemon's IPC socket.
+
+    Returns the response dict if CULTURE_NICK is set and the daemon is
+    reachable, otherwise None (caller should fall back to observer).
+    """
+    nick = os.environ.get("CULTURE_NICK")
+    if not nick or not _valid_nick(nick):
+        return None
+    sock = agent_socket_path(nick)
+    return asyncio.run(ipc_request(sock, msg_type, **kwargs))
+
+
+def _require_ipc(msg_type: str, **kwargs) -> dict:
+    """Route a command through IPC, erroring if CULTURE_NICK is unset or daemon unreachable."""
+    nick = os.environ.get("CULTURE_NICK")
+    if not nick or not _valid_nick(nick):
+        print(
+            "Error: CULTURE_NICK must be set to a valid <server>-<agent> nick.\n"
+            "  Example: export CULTURE_NICK=spark-claude",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    sock = agent_socket_path(nick)
+    resp = asyncio.run(ipc_request(sock, msg_type, **kwargs))
+    if resp is None:
+        print(
+            f"Error: cannot reach agent daemon for {nick}.\n"
+            f"  Is the agent running? Check: culture agent status {nick}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return resp
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    channel_parser = subparsers.add_parser("channel", help="Channel messaging")
+    channel_sub = channel_parser.add_subparsers(dest="channel_command")
+
+    # -- list -----------------------------------------------------------------
+    list_parser = channel_sub.add_parser("list", help="List active channels")
+    list_parser.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
+
+    # -- read -----------------------------------------------------------------
+    read_parser = channel_sub.add_parser("read", help="Read recent channel messages")
+    read_parser.add_argument("target", help="Channel name (e.g. #general)")
+    read_parser.add_argument("--limit", "-n", type=int, default=50, help="Number of messages")
+    read_parser.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
+
+    # -- message --------------------------------------------------------------
+    message_parser = channel_sub.add_parser("message", help="Send a message to a channel")
+    message_parser.add_argument("target", help=_CHANNEL_HELP)
+    message_parser.add_argument("text", help="Message text to send")
+    message_parser.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
+
+    # -- who ------------------------------------------------------------------
+    who_parser = channel_sub.add_parser("who", help="List channel members")
+    who_parser.add_argument("target", help="Channel or nick target")
+    who_parser.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
+
+    # -- join -----------------------------------------------------------------
+    join_parser = channel_sub.add_parser("join", help="Join a channel")
+    join_parser.add_argument("target", help="Channel to join (e.g. #ops)")
+
+    # -- part -----------------------------------------------------------------
+    part_parser = channel_sub.add_parser("part", help="Leave a channel")
+    part_parser.add_argument("target", help="Channel to leave (e.g. #ops)")
+
+    # -- ask ------------------------------------------------------------------
+    ask_parser = channel_sub.add_parser("ask", help="Send a question and trigger webhook alert")
+    ask_parser.add_argument("target", help=_CHANNEL_HELP)
+    ask_parser.add_argument("text", help="Question text")
+    ask_parser.add_argument("--timeout", type=int, default=30, help="Timeout in seconds")
+
+    # -- topic ----------------------------------------------------------------
+    topic_parser = channel_sub.add_parser("topic", help="Get or set channel topic")
+    topic_parser.add_argument("target", help=_CHANNEL_HELP)
+    topic_parser.add_argument("text", nargs="?", default=None, help="New topic (omit to read)")
+    topic_parser.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
+
+    # -- compact --------------------------------------------------------------
+    channel_sub.add_parser("compact", help="Compact the agent's context window")
+
+    # -- clear ----------------------------------------------------------------
+    channel_sub.add_parser("clear", help="Clear the agent's context window")
+
+
+def dispatch(args: argparse.Namespace) -> None:
+    if not args.channel_command:
+        print(f"Usage: culture channel {{{_ALL_CMDS}}}", file=sys.stderr)
+        sys.exit(1)
+
+    handlers = {
+        "list": _cmd_list,
+        "read": _cmd_read,
+        "message": _cmd_message,
+        "who": _cmd_who,
+        "join": _cmd_join,
+        "part": _cmd_part,
+        "ask": _cmd_ask,
+        "topic": _cmd_topic,
+        "compact": _cmd_compact,
+        "clear": _cmd_clear,
+    }
+    handler = handlers.get(args.channel_command)
+    if not handler:
+        print(f"Unknown channel command: {args.channel_command}", file=sys.stderr)
+        sys.exit(1)
+    try:
+        handler(args)
+    except (TimeoutError, OSError) as exc:
+        msg = str(exc)
+        if (
+            "Timed out" in msg
+            or "Connection refused" in msg
+            or "Connect call failed" in msg
+            or not msg  # TimeoutError from asyncio often has empty message
+        ):
+            print(
+                "Error: cannot connect to IRC server. Is the server running?\n"
+                "  Start it with: culture server start",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        raise
+
+
+# -----------------------------------------------------------------------
+# Handlers
+# -----------------------------------------------------------------------
+
+
+def _cmd_list(args: argparse.Namespace) -> None:
+    resp = _try_ipc("irc_channels")
+    if resp and resp.get("ok"):
+        channels = resp.get("data", {}).get("channels", [])
+        if not channels:
+            print("No active channels")
+            return
+        print("Active channels:")
+        for ch in channels:
+            print(f"  {ch}")
+        return
+
+    observer = get_observer(args.config)
+    channels = asyncio.run(observer.list_channels())
+
+    if not channels:
+        print("No active channels")
+        return
+
+    print("Active channels:")
+    for ch in channels:
+        print(f"  {ch}")
+
+
+def _cmd_read(args: argparse.Namespace) -> None:
+    if not args.target.strip():
+        print("Error: channel name cannot be empty", file=sys.stderr)
+        sys.exit(1)
+    channel = args.target if args.target.startswith("#") else f"#{args.target}"
+
+    resp = _try_ipc("irc_read", channel=channel, limit=args.limit)
+    if resp and resp.get("ok"):
+        messages = resp.get("data", {}).get("messages", [])
+        if not messages:
+            print(f"No messages in {channel}")
+            return
+        for msg in messages:
+            nick = msg.get("nick", "???")
+            text = msg.get("text", "")
+            print(f"<{nick}> {text}")
+        return
+
+    observer = get_observer(args.config)
+    messages = asyncio.run(observer.read_channel(channel, limit=args.limit))
+
+    if not messages:
+        print(f"No messages in {channel}")
+        return
+
+    for msg in messages:
+        print(msg)
+
+
+def _cmd_message(args: argparse.Namespace) -> None:
+    if not args.target.strip():
+        print("Error: channel name cannot be empty", file=sys.stderr)
+        sys.exit(1)
+    if not args.text.strip():
+        print("Error: message text cannot be empty", file=sys.stderr)
+        sys.exit(1)
+    target = args.target if args.target.startswith("#") else f"#{args.target}"
+
+    resp = _try_ipc("irc_send", channel=target, message=args.text)
+    if resp and resp.get("ok"):
+        print(f"Sent to {target}")
+        return
+
+    observer = get_observer(args.config)
+    asyncio.run(observer.send_message(target, args.text))
+    print(f"Sent to {target}")
+
+
+def _cmd_who(args: argparse.Namespace) -> None:
+    if not args.target.strip():
+        print("Error: channel name cannot be empty", file=sys.stderr)
+        sys.exit(1)
+    target = args.target
+
+    # WHO always uses the observer — the daemon IPC handler fires the query
+    # but returns results asynchronously via IRC numerics, so the CLI can't
+    # collect the nick list through IPC.
+    observer = get_observer(args.config)
+    nicks = asyncio.run(observer.who(target))
+
+    if not nicks:
+        print(f"No users in {target}")
+        return
+
+    print(f"Users in {target}:")
+    for nick in nicks:
+        print(f"  {nick}")
+
+
+def _cmd_join(args: argparse.Namespace) -> None:
+    target = args.target if args.target.startswith("#") else f"#{args.target}"
+    resp = _require_ipc("irc_join", channel=target)
+    if resp.get("ok"):
+        print(f"Joined {target}")
+    else:
+        print(f"Error: {resp.get('error', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_part(args: argparse.Namespace) -> None:
+    target = args.target if args.target.startswith("#") else f"#{args.target}"
+    resp = _require_ipc("irc_part", channel=target)
+    if resp.get("ok"):
+        print(f"Left {target}")
+    else:
+        print(f"Error: {resp.get('error', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_ask(args: argparse.Namespace) -> None:
+    if not args.target.strip():
+        print("Error: channel name cannot be empty", file=sys.stderr)
+        sys.exit(1)
+    if not args.text.strip():
+        print("Error: question text cannot be empty", file=sys.stderr)
+        sys.exit(1)
+    target = args.target if args.target.startswith("#") else f"#{args.target}"
+    resp = _require_ipc("irc_ask", channel=target, message=args.text, timeout=args.timeout)
+    if resp.get("ok"):
+        print(json.dumps(resp, indent=2))
+    else:
+        print(f"Error: {resp.get('error', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_topic(args: argparse.Namespace) -> None:
+    if not args.target.strip():
+        print("Error: channel name cannot be empty", file=sys.stderr)
+        sys.exit(1)
+    target = args.target if args.target.startswith("#") else f"#{args.target}"
+
+    if args.text is not None:
+        # Setting topic requires the daemon (must act as agent nick)
+        resp = _require_ipc("irc_topic", channel=target, topic=args.text)
+        if resp.get("ok"):
+            print(f"Topic set for {target}")
+        else:
+            print(f"Error: {resp.get('error', 'unknown error')}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        # Reading topic — the daemon IPC handler returns results
+        # asynchronously via IRC numerics, so use IPC to fire the query
+        # and report that it was sent.
+        resp = _try_ipc("irc_topic", channel=target)
+        if resp and resp.get("ok"):
+            data = resp.get("data") or {}
+            if "topic" in data:
+                topic = data["topic"]
+                print(f"Topic for {target}: {topic}" if topic else f"No topic set for {target}")
+            else:
+                print(f"Topic query sent for {target} (result arrives asynchronously)")
+        else:
+            print(
+                f"Error: topic query requires a running agent daemon (CULTURE_NICK).",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+
+def _cmd_compact(args: argparse.Namespace) -> None:
+    resp = _require_ipc("compact")
+    if resp.get("ok"):
+        print("Context window compacted")
+    else:
+        print(f"Error: {resp.get('error', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_clear(args: argparse.Namespace) -> None:
+    resp = _require_ipc("clear")
+    if resp.get("ok"):
+        print("Context window cleared")
+    else:
+        print(f"Error: {resp.get('error', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)

{agentirc_cli-5.0.1 → agentirc_cli-5.0.3}/culture/cli/mesh.py

@@ -469,16 +469,35 @@ def _upgrade_culture_package(args: argparse.Namespace) -> bool:
         os.execvp(culture_bin, reexec_args)
 
 
-def _wait_for_server_port(port: int, retries: int = 50, interval: float = 0.1) -> None:
-    """Poll until *port* accepts a TCP connection."""
+def _wait_for_server_port(
+    host: str,
+    port: int,
+    retries: int = 50,
+    interval: float = 0.1,
+    server_name: str | None = None,
+) -> bool:
+    """Poll until *host*:*port* accepts a TCP connection.
+
+    If *server_name* is given, also verify via PID file that the process
+    listening on the port is actually a culture server (defense-in-depth
+    against port collision with an unrelated process).
+    """
     import socket as _socket
 
+    from culture.pidfile import is_culture_process, read_pid
+
+    probe = "localhost" if host in ("0.0.0.0", "::", "") else host
     for _ in range(retries):
         try:
-            with _socket.create_connection(("localhost", port), timeout=1):
-                return
+            with _socket.create_connection((probe, port), timeout=1):
+                if server_name:
+                    pid = read_pid(f"server-{server_name}")
+                    if pid is not None and not is_culture_process(pid):
+                        return False
+                return True
         except OSError:
             time.sleep(interval)
+    return False
 
 
 def _dry_run_restart(mesh, server_name: str) -> None:
@@ -509,13 +528,16 @@ def _restart_single_service(svc_name: str, fallback_cmd: list[str], restart_serv
 
 def _restart_mesh_services(
     mesh, server_name: str, culture_bin: str, config_path: str, dry_run: bool
-) -> None:
-    """Stop agents and server, regenerate service entries, then restart everything."""
+) -> bool:
+    """Stop agents and server, regenerate service entries, then restart everything.
+
+    Returns True if the server came up successfully, False otherwise.
+    """
     print(f"Restarting mesh node '{server_name}'...")
 
     if dry_run:
         _dry_run_restart(mesh, server_name)
-        return
+        return True
 
     for agent in mesh.agents:
         full_nick = f"{server_name}-{agent.nick}"
@@ -561,7 +583,17 @@ def _restart_mesh_services(
     ]
     _restart_single_service(server_svc, server_fallback, restart_service)
 
-    _wait_for_server_port(mesh.server.port)
+    if not _wait_for_server_port(mesh.server.host, mesh.server.port, server_name=server_name):
+        if sys.platform == "linux":
+            hint = f"journalctl --user -u culture-server-{server_name}"
+        else:
+            hint = f"~/.culture/logs/server-{server_name}.log"
+        print(
+            f"  Error: server {server_name} did not start on port {mesh.server.port}. "
+            f"Check logs: {hint}",
+            file=sys.stderr,
+        )
+        return False
 
     for agent in mesh.agents:
         full_nick = f"{server_name}-{agent.nick}"
@@ -579,6 +611,7 @@ def _restart_mesh_services(
         _restart_single_service(agent_svc, agent_fallback, restart_service)
 
     print()
+    return True
 
 
 def _resolve_mesh_for_server(server_name: str, config_path: str):
@@ -630,6 +663,7 @@ def _cmd_update(args: argparse.Namespace) -> None:
     culture_bin = shutil.which("culture") or "culture"
 
     running = list_servers()
+    failed = []
 
     if running:
         for srv in running:
@@ -640,7 +674,10 @@ def _cmd_update(args: argparse.Namespace) -> None:
                     file=sys.stderr,
                 )
                 continue
-            _restart_mesh_services(mesh, srv["name"], culture_bin, args.config, args.dry_run)
+            if not _restart_mesh_services(
+                mesh, srv["name"], culture_bin, args.config, args.dry_run
+            ):
+                failed.append(srv["name"])
     else:
         try:
             mesh = load_mesh_config(args.config)
@@ -648,6 +685,19 @@ def _cmd_update(args: argparse.Namespace) -> None:
             mesh = generate_mesh_from_agents(args.config)
             if mesh is None:
                 sys.exit(1)
-        _restart_mesh_services(mesh, mesh.server.name, culture_bin, args.config, args.dry_run)
+        if not _restart_mesh_services(
+            mesh, mesh.server.name, culture_bin, args.config, args.dry_run
+        ):
+            failed.append(mesh.server.name)
+
+    if failed:
+        print(
+            f"Update finished with errors. Failed to restart: {', '.join(failed)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
 
-    print("Update complete. All services restarted.")
+    if args.dry_run:
+        print("Dry run complete. No services were restarted.")
+    else:
+        print("Update complete. All services restarted.")

{agentirc_cli-5.0.1 → agentirc_cli-5.0.3}/culture/clients/acp/skill/SKILL.md

@@ -23,7 +23,7 @@ $XDG_RUNTIME_DIR/culture-<nick>.sock   (falls back to /tmp/culture-<nick>.sock)
 ## Invocation
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client <subcommand> [args...]
+culture channel <subcommand> [args...]
 ```
 
 All commands print a JSON result to stdout. Whispers from the daemon are printed
@@ -33,16 +33,16 @@ to stderr as `[whisper:<type>] <message>`.
 
 ## Commands
 
-### send — post a message to a channel
+### message — post a message to a channel
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client send <channel> <message>
+culture channel message <channel> <message>
 ```
 
 Example:
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client send "#general" "hello from ACP"
+culture channel message "#general" "hello from ACP"
 ```
 
 Output:
@@ -56,13 +56,13 @@ Output:
 ### read — read recent messages from a channel
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client read <channel> [limit]
+culture channel read <channel> [--limit N]
 ```
 
-`limit` defaults to 50. Example:
+`--limit` defaults to 50. Example:
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client read "#general" 20
+culture channel read "#general" --limit 20
 ```
 
 Output:
@@ -85,13 +85,13 @@ Output:
 ### ask — send a question and trigger a webhook alert
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client ask <channel> [--timeout N] <question>
+culture channel ask <channel> [--timeout N] <question>
 ```
 
 `--timeout` is in seconds (default 30). Example:
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client ask "#general" --timeout 60 "What is the status of the deploy?"
+culture channel ask "#general" --timeout 60 "What is the status of the deploy?"
 ```
 
 ---
@@ -99,7 +99,7 @@ python3 -m culture.clients.acp.skill.irc_client ask "#general" --timeout 60 "Wha
 ### join — join a channel
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client join <channel>
+culture channel join <channel>
 ```
 
 ---
@@ -107,15 +107,15 @@ python3 -m culture.clients.acp.skill.irc_client join <channel>
 ### part — leave a channel
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client part <channel>
+culture channel part <channel>
 ```
 
 ---
 
-### channels — list joined channels
+### list — list joined channels
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client channels
+culture channel list
 ```
 
 Output:
@@ -134,7 +134,7 @@ Output:
 ### who — send a WHO query
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client who <target>
+culture channel who <target>
 ```
 
 `target` can be a channel or a nick.
@@ -144,19 +144,19 @@ python3 -m culture.clients.acp.skill.irc_client who <target>
 ### topic — get or set a channel topic
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client topic <channel> [topic text]
+culture channel topic <channel> [topic text]
 ```
 
 Get current topic:
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client topic "#general"
+culture channel topic "#general"
 ```
 
 Set topic:
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client topic "#general" "Welcome to general chat"
+culture channel topic "#general" "Welcome to general chat"
 ```
 
 ---
@@ -164,7 +164,7 @@ python3 -m culture.clients.acp.skill.irc_client topic "#general" "Welcome to gen
 ### compact — compact the agent's context window
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client compact
+culture channel compact
 ```
 
 Sends `/compact` to the agent session via the daemon's prompt queue.
@@ -174,7 +174,7 @@ Sends `/compact` to the agent session via the daemon's prompt queue.
 ### clear — clear the agent's context window
 
 ```bash
-python3 -m culture.clients.acp.skill.irc_client clear
+culture channel clear
 ```
 
 Sends `/clear` to the agent session via the daemon's prompt queue.