agentirc-cli 4.3.2__tar.gz → 4.3.4__tar.gz

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/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/).
 
+## [4.3.4] - 2026-04-07
+
+
+### Changed
+
+- Extract duplicated string literals into named constants (SonarCloud S1192)
+- Refactor cli/_helpers.py into modular cli/shared/ package (constants, ipc, process, mesh, display)
+
+## [4.3.3] - 2026-04-07
+
+
+### Changed
+
+- Reduced cognitive complexity in 40 functions across 25 files to meet SonarCloud threshold (≤15)
+
 ## [4.3.2] - 2026-04-07
 
 

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/PKG-INFO

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

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/culture/bots/bot_manager.py

@@ -13,6 +13,8 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+BOT_CONFIG_FILE = "bot.yaml"
+
 
 class BotManager:
     """Loads, starts, stops, and dispatches webhooks to bots."""
@@ -27,7 +29,7 @@ class BotManager:
             return
 
         for bot_dir in sorted(BOTS_DIR.iterdir()):
-            yaml_path = bot_dir / "bot.yaml"
+            yaml_path = bot_dir / BOT_CONFIG_FILE
             if not yaml_path.is_file():
                 continue
             try:
@@ -45,7 +47,7 @@ class BotManager:
     async def create_bot(self, config: BotConfig) -> Bot:
         """Create a new bot: write config to disk and start it."""
         bot_dir = BOTS_DIR / config.name
-        save_bot_config(bot_dir / "bot.yaml", config)
+        save_bot_config(bot_dir / BOT_CONFIG_FILE, config)
 
         bot = Bot(config, self.server)
         self.bots[config.name] = bot
@@ -57,7 +59,7 @@ class BotManager:
         bot = self.bots.get(name)
         if not bot:
             # Try loading from disk
-            yaml_path = BOTS_DIR / name / "bot.yaml"
+            yaml_path = BOTS_DIR / name / BOT_CONFIG_FILE
             if not yaml_path.is_file():
                 raise ValueError(f"Bot {name!r} not found")
             config = load_bot_config(yaml_path)

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/culture/cli/agent.py

@@ -27,18 +27,16 @@ from culture.pidfile import (
     write_pid,
 )
 
-from ._helpers import (
+from .shared.constants import (
     _CONFIG_HELP,
+    DEFAULT_CHANNEL,
     DEFAULT_CONFIG,
     LOG_DIR,
-    agent_socket_path,
-    get_observer,
-    ipc_request,
-    print_agent_detail,
-    print_agents_overview,
-    print_bot_listing,
-    stop_agent,
+    NO_AGENTS_MSG,
 )
+from .shared.display import print_agent_detail, print_agents_overview, print_bot_listing
+from .shared.ipc import agent_socket_path, get_observer, ipc_request
+from .shared.process import stop_agent
 
 logger = logging.getLogger("culture")
 
@@ -212,7 +210,7 @@ def _create_agent_config(args: argparse.Namespace, full_nick: str) -> AgentConfi
             nick=full_nick,
             agent="codex",
             directory=os.getcwd(),
-            channels=["#general"],
+            channels=[DEFAULT_CHANNEL],
         )
     if args.agent == "copilot":
         from culture.clients.copilot.config import AgentConfig as CopilotAgentConfig
@@ -221,7 +219,7 @@ def _create_agent_config(args: argparse.Namespace, full_nick: str) -> AgentConfi
             nick=full_nick,
             agent="copilot",
             directory=os.getcwd(),
-            channels=["#general"],
+            channels=[DEFAULT_CHANNEL],
         )
     if args.agent == "acp":
         import json as _json
@@ -246,13 +244,13 @@ def _create_agent_config(args: argparse.Namespace, full_nick: str) -> AgentConfi
             agent="acp",
             acp_command=acp_cmd,
             directory=os.getcwd(),
-            channels=["#general"],
+            channels=[DEFAULT_CHANNEL],
         )
     return AgentConfig(
         nick=full_nick,
         agent=args.agent,
         directory=os.getcwd(),
-        channels=["#general"],
+        channels=[DEFAULT_CHANNEL],
     )
 
 
@@ -365,7 +363,7 @@ def _resolve_agents_to_start(config, args) -> list:
         agents = _resolve_auto(config)
 
     if not agents:
-        print("No agents configured", file=sys.stderr)
+        print(NO_AGENTS_MSG, file=sys.stderr)
         sys.exit(1)
     return agents
 
@@ -541,7 +539,7 @@ def _cmd_stop(args: argparse.Namespace) -> None:
         if len(config.agents) == 1:
             agents = config.agents
         elif len(config.agents) == 0:
-            print("No agents configured", file=sys.stderr)
+            print(NO_AGENTS_MSG, file=sys.stderr)
             sys.exit(1)
         else:
             print(
@@ -574,14 +572,14 @@ def _no_agents_message(config, show_all: bool) -> str:
         archived_count = sum(1 for a in config.agents if a.archived)
         if archived_count:
             return f"No active agents ({archived_count} archived, use --all to show)"
-    return "No agents configured"
+    return NO_AGENTS_MSG
 
 
 def _cmd_status(args: argparse.Namespace) -> None:
     config = load_config_or_default(args.config)
 
     if not config.agents:
-        print("No agents configured")
+        print(NO_AGENTS_MSG)
         return
 
     if args.nick:

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/culture/cli/bot.py

@@ -8,7 +8,7 @@ import time
 
 from culture.clients.claude.config import load_config_or_default
 
-from ._helpers import _CONFIG_HELP, DEFAULT_CONFIG
+from .shared.constants import _BOT_NAME_HELP, _CONFIG_HELP, BOT_CONFIG_FILE, DEFAULT_CONFIG
 
 NAME = "bot"
 
@@ -31,11 +31,11 @@ def register(subparsers: argparse._SubParsersAction) -> None:
     bot_create.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
 
     bot_start = bot_sub.add_parser("start", help="Start a bot")
-    bot_start.add_argument("name", help="Bot name")
+    bot_start.add_argument("name", help=_BOT_NAME_HELP)
     bot_start.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
 
     bot_stop = bot_sub.add_parser("stop", help="Stop a bot")
-    bot_stop.add_argument("name", help="Bot name")
+    bot_stop.add_argument("name", help=_BOT_NAME_HELP)
     bot_stop.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
 
     bot_list = bot_sub.add_parser("list", help="List bots")
@@ -43,7 +43,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:
     bot_list.add_argument("--all", action="store_true", help="Include archived bots")
 
     bot_inspect = bot_sub.add_parser("inspect", help="Show bot details")
-    bot_inspect.add_argument("name", help="Bot name")
+    bot_inspect.add_argument("name", help=_BOT_NAME_HELP)
     bot_inspect.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
 
     bot_archive = bot_sub.add_parser("archive", help="Archive a bot")
@@ -113,11 +113,11 @@ def _bot_create(args: argparse.Namespace) -> None:
     )
 
     bot_dir = BOTS_DIR / name
-    if (bot_dir / "bot.yaml").exists():
+    if (bot_dir / BOT_CONFIG_FILE).exists():
         print(f"Bot '{name}' already exists at {bot_dir}", file=sys.stderr)
         sys.exit(1)
 
-    save_bot_config(bot_dir / "bot.yaml", bot_config)
+    save_bot_config(bot_dir / BOT_CONFIG_FILE, bot_config)
     print(f"Bot '{name}' created at {bot_dir}")
     print(f"  Owner:    {args.owner}")
     print(f"  Trigger:  {args.trigger}")
@@ -132,7 +132,7 @@ def _bot_start(args: argparse.Namespace) -> None:
     from culture.bots.config import BOTS_DIR
 
     bot_dir = BOTS_DIR / args.name
-    if not (bot_dir / "bot.yaml").exists():
+    if not (bot_dir / BOT_CONFIG_FILE).exists():
         print(f"Bot '{args.name}' not found at {bot_dir}", file=sys.stderr)
         sys.exit(1)
 
@@ -144,7 +144,7 @@ def _bot_stop(args: argparse.Namespace) -> None:
     from culture.bots.config import BOTS_DIR
 
     bot_dir = BOTS_DIR / args.name
-    if not (bot_dir / "bot.yaml").exists():
+    if not (bot_dir / BOT_CONFIG_FILE).exists():
         print(f"Bot '{args.name}' not found at {bot_dir}", file=sys.stderr)
         sys.exit(1)
 
@@ -161,7 +161,7 @@ def _load_and_filter_bots(args) -> list:
     show_all = getattr(args, "all", False)
     bots = []
     for bot_dir in sorted(BOTS_DIR.iterdir()):
-        yaml_path = bot_dir / "bot.yaml"
+        yaml_path = bot_dir / BOT_CONFIG_FILE
         if not yaml_path.is_file():
             continue
         try:
@@ -203,7 +203,7 @@ def _bot_inspect(args: argparse.Namespace) -> None:
     from culture.bots.config import BOTS_DIR, load_bot_config
 
     bot_dir = BOTS_DIR / args.name
-    yaml_path = bot_dir / "bot.yaml"
+    yaml_path = bot_dir / BOT_CONFIG_FILE
     if not yaml_path.is_file():
         print(f"Bot '{args.name}' not found at {bot_dir}", file=sys.stderr)
         sys.exit(1)
@@ -245,7 +245,7 @@ def _bot_archive(args: argparse.Namespace) -> None:
     from culture.bots.config import BOTS_DIR, load_bot_config, save_bot_config
 
     bot_dir = BOTS_DIR / args.name
-    yaml_path = bot_dir / "bot.yaml"
+    yaml_path = bot_dir / BOT_CONFIG_FILE
     if not yaml_path.is_file():
         print(f"Bot '{args.name}' not found at {bot_dir}", file=sys.stderr)
         sys.exit(1)
@@ -270,7 +270,7 @@ def _bot_unarchive(args: argparse.Namespace) -> None:
     from culture.bots.config import BOTS_DIR, load_bot_config, save_bot_config
 
     bot_dir = BOTS_DIR / args.name
-    yaml_path = bot_dir / "bot.yaml"
+    yaml_path = bot_dir / BOT_CONFIG_FILE
     if not yaml_path.is_file():
         print(f"Bot '{args.name}' not found at {bot_dir}", file=sys.stderr)
         sys.exit(1)

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/culture/cli/channel.py

@@ -6,7 +6,8 @@ import argparse
 import asyncio
 import sys
 
-from ._helpers import _CONFIG_HELP, DEFAULT_CONFIG, get_observer
+from .shared.constants import _CONFIG_HELP, DEFAULT_CONFIG
+from .shared.ipc import get_observer
 
 NAME = "channel"
 

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/culture/cli/mesh.py

@@ -17,13 +17,9 @@ from culture.clients.claude.config import (
 )
 from culture.pidfile import is_process_alive, read_pid
 
-from ._helpers import (
-    DEFAULT_CONFIG,
-    build_server_start_cmd,
-    generate_mesh_from_agents,
-    server_stop_by_name,
-    stop_agent,
-)
+from .shared.constants import AGENTS_YAML, CULTURE_DIR, DEFAULT_CONFIG
+from .shared.mesh import build_server_start_cmd, generate_mesh_from_agents
+from .shared.process import server_stop_by_name, stop_agent
 
 logger = logging.getLogger("culture")
 
@@ -313,7 +309,7 @@ def _generate_agent_configs(mesh, server_name: str) -> None:
 
     for workdir, agents in workdir_agents.items():
         os.makedirs(workdir, exist_ok=True)
-        config_path = os.path.join(workdir, ".culture", "agents.yaml")
+        config_path = os.path.join(workdir, CULTURE_DIR, AGENTS_YAML)
         os.makedirs(os.path.dirname(config_path), exist_ok=True)
 
         agent_configs = []
@@ -348,7 +344,7 @@ def _install_mesh_services(mesh, server_name: str, culture_bin: str, config_path
     for agent in mesh.agents:
         full_nick = f"{server_name}-{agent.nick}"
         workdir = os.path.expanduser(agent.workdir)
-        agent_config_path = os.path.join(workdir, ".culture", "agents.yaml")
+        agent_config_path = os.path.join(workdir, CULTURE_DIR, AGENTS_YAML)
         agent_cmd = [
             culture_bin,
             "agent",
@@ -502,7 +498,7 @@ def _restart_mesh_services(
     for agent in mesh.agents:
         full_nick = f"{server_name}-{agent.nick}"
         workdir = os.path.expanduser(agent.workdir)
-        agent_config_path = os.path.join(workdir, ".culture", "agents.yaml")
+        agent_config_path = os.path.join(workdir, CULTURE_DIR, AGENTS_YAML)
         agent_cmd = [
             culture_bin,
             "agent",
@@ -549,7 +545,7 @@ def _restart_mesh_services(
         print(f"  Restarting {agent_svc}...")
         if not restart_service(agent_svc):
             workdir = os.path.expanduser(agent.workdir)
-            agent_config_path = os.path.join(workdir, ".culture", "agents.yaml")
+            agent_config_path = os.path.join(workdir, CULTURE_DIR, AGENTS_YAML)
             subprocess.run(
                 [culture_bin, "agent", "start", full_nick, "--config", agent_config_path],
                 check=False,

{agentirc_cli-4.3.2 → agentirc_cli-4.3.4}/culture/cli/server.py

@@ -19,7 +19,14 @@ from culture.pidfile import (
     write_pid,
 )
 
-from ._helpers import LOG_DIR, parse_link, resolve_links_from_mesh
+from .shared.constants import (
+    _CONFIG_HELP,
+    _SERVER_NAME_HELP,
+    BOT_CONFIG_FILE,
+    DEFAULT_CONFIG,
+    LOG_DIR,
+)
+from .shared.mesh import parse_link, resolve_links_from_mesh
 
 logger = logging.getLogger("culture")
 
@@ -31,7 +38,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:
     server_sub = server_parser.add_subparsers(dest="server_command")
 
     srv_start = server_sub.add_parser("start", help="Start the IRC server daemon")
-    srv_start.add_argument("--name", default="culture", help="Server name")
+    srv_start.add_argument("--name", default="culture", help=_SERVER_NAME_HELP)
     srv_start.add_argument("--host", default="0.0.0.0", help="Listen address")
     srv_start.add_argument("--port", type=int, default=6667, help="Listen port")
     srv_start.add_argument(
@@ -59,10 +66,10 @@ def register(subparsers: argparse._SubParsersAction) -> None:
     )
 
     srv_stop = server_sub.add_parser("stop", help="Stop the IRC server daemon")
-    srv_stop.add_argument("--name", default="culture", help="Server name")
+    srv_stop.add_argument("--name", default="culture", help=_SERVER_NAME_HELP)
 
     srv_status = server_sub.add_parser("status", help="Check server daemon status")
-    srv_status.add_argument("--name", default="culture", help="Server name")
+    srv_status.add_argument("--name", default="culture", help=_SERVER_NAME_HELP)
 
     srv_default = server_sub.add_parser("default", help="Set default server")
     srv_default.add_argument("name", help="Server name to set as default")
@@ -73,29 +80,29 @@ def register(subparsers: argparse._SubParsersAction) -> None:
     srv_rename.add_argument("new_name", help="New server name")
     srv_rename.add_argument(
         "--config",
-        default=os.path.expanduser("~/.culture/agents.yaml"),
-        help="Config file path",
+        default=DEFAULT_CONFIG,
+        help=_CONFIG_HELP,
     )
 
     srv_archive = server_sub.add_parser(
         "archive", help="Archive the server and all its agents/bots"
     )
-    srv_archive.add_argument("--name", default="culture", help="Server name")
+    srv_archive.add_argument("--name", default="culture", help=_SERVER_NAME_HELP)
     srv_archive.add_argument("--reason", default="", help="Reason for archiving")
     srv_archive.add_argument(
         "--config",
-        default=os.path.expanduser("~/.culture/agents.yaml"),
-        help="Config file path",
+        default=DEFAULT_CONFIG,
+        help=_CONFIG_HELP,
     )
 
     srv_unarchive = server_sub.add_parser(
         "unarchive", help="Restore an archived server and all its agents/bots"
     )
-    srv_unarchive.add_argument("--name", default="culture", help="Server name")
+    srv_unarchive.add_argument("--name", default="culture", help=_SERVER_NAME_HELP)
     srv_unarchive.add_argument(
         "--config",
-        default=os.path.expanduser("~/.culture/agents.yaml"),
-        help="Config file path",
+        default=DEFAULT_CONFIG,
+        help=_CONFIG_HELP,
     )
 
 
@@ -256,7 +263,7 @@ def _server_start(args: argparse.Namespace) -> None:
     # Check if server is archived
     from culture.clients.claude.config import load_config_or_default
 
-    config_path = getattr(args, "config", os.path.expanduser("~/.culture/agents.yaml"))
+    config_path = getattr(args, "config", DEFAULT_CONFIG)
     config = load_config_or_default(config_path)
     if config.server.name == args.name and config.server.archived:
         print(
@@ -439,7 +446,7 @@ def _set_bots_archive_state(agent_nicks: set, *, archive: bool, reason: str = ""
         return changed
     today = time.strftime("%Y-%m-%d")
     for bot_dir in BOTS_DIR.iterdir():
-        yaml_path = bot_dir / "bot.yaml"
+        yaml_path = bot_dir / BOT_CONFIG_FILE
         if not yaml_path.is_file():
             continue
         try:
@@ -486,7 +493,7 @@ def _server_archive(args: argparse.Namespace) -> None:
         _server_stop(args)
 
     # Stop all running agents
-    from culture.cli._helpers import stop_agent
+    from culture.cli.shared.process import stop_agent
 
     for agent in config.agents:
         agent_pid = read_pid(f"agent-{agent.nick}")

agentirc_cli-4.3.4/culture/cli/shared/constants.py

@@ -0,0 +1,16 @@
+"""Shared constants for culture CLI modules."""
+
+import os
+
+DEFAULT_CONFIG = os.path.expanduser("~/.culture/agents.yaml")
+LOG_DIR = os.path.expanduser("~/.culture/logs")
+
+_CONFIG_HELP = "Config file path"
+_SERVER_NAME_HELP = "Server name"
+_BOT_NAME_HELP = "Bot name"
+
+BOT_CONFIG_FILE = "bot.yaml"
+DEFAULT_CHANNEL = "#general"
+NO_AGENTS_MSG = "No agents configured"
+CULTURE_DIR = ".culture"
+AGENTS_YAML = "agents.yaml"

agentirc_cli-4.3.4/culture/cli/shared/display.py

@@ -0,0 +1,131 @@
+"""Agent and bot status display helpers for culture CLI."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+
+from culture.pidfile import is_process_alive, read_pid, remove_pid
+
+from .constants import BOT_CONFIG_FILE
+from .ipc import agent_socket_path, ipc_request
+
+logger = logging.getLogger("culture")
+
+
+def agent_process_status(agent) -> tuple[str, int | None]:
+    """Return (status_str, pid_or_none) for an agent."""
+    pid_name = f"agent-{agent.nick}"
+    pid = read_pid(pid_name)
+    if pid and is_process_alive(pid):
+        socket_path = agent_socket_path(agent.nick)
+        if os.path.exists(socket_path):
+            return "running", pid
+        return "starting", pid
+    if pid:
+        remove_pid(pid_name)
+    return "stopped", None
+
+
+def print_agent_detail(agent, config_path: str, args: argparse.Namespace) -> None:
+    """Print detailed status for a single agent, including live IPC activity query."""
+    status, pid = agent_process_status(agent)
+    print(agent.nick)
+    print(f"  Status:     {status}")
+    print(f"  PID:        {pid or '-'}")
+
+    if status == "running":
+        resp = asyncio.run(ipc_request(agent_socket_path(agent.nick), "status", query=True))
+        if resp and resp.get("ok"):
+            data = resp.get("data", {})
+            print(f"  Activity:   {data.get('description', 'nothing')}")
+            print(f"  Turns:      {data.get('turn_count', 0)}")
+            print(f"  Paused:     {'yes' if data.get('paused') else 'no'}")
+        else:
+            print("  Activity:   unknown (daemon may need restart)")
+    else:
+        print("  Activity:   -")
+
+    channels = agent.channels if isinstance(agent.channels, list) else []
+    print(f"  Directory:  {agent.directory}")
+    print(f"  Backend:    {agent.agent}")
+    print(f"  Channels:   {', '.join(channels)}")
+    print(f"  Model:      {agent.model}")
+    print(f"  Config:     {config_path}")
+
+
+def _format_agent_status(base_status: str, archived: bool, show_archived_marker: bool) -> str:
+    """Format the display status string for an agent."""
+    if not archived:
+        return base_status
+    if show_archived_marker:
+        return f"{base_status} (archived)"
+    if base_status == "stopped":
+        return "archived"
+    return base_status
+
+
+def _fetch_agent_activity(agent) -> str:
+    """Fetch activity description from a running agent via IPC."""
+    resp = asyncio.run(ipc_request(agent_socket_path(agent.nick), "status"))
+    if resp and resp.get("ok"):
+        return resp.get("data", {}).get("description", "nothing")
+    return "-"
+
+
+def print_agents_overview(
+    agents: list, show_activity: bool, show_archived_marker: bool = False
+) -> None:
+    """Print a table of all agents with status, PID, and optionally activity."""
+    if show_activity:
+        print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10} {'ACTIVITY'}")
+        print("-" * 72)
+    else:
+        print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10}")
+        print("-" * 52)
+
+    for agent in agents:
+        base_status, pid = agent_process_status(agent)
+        status = _format_agent_status(
+            base_status, getattr(agent, "archived", False), show_archived_marker
+        )
+        activity = (
+            _fetch_agent_activity(agent) if show_activity and base_status == "running" else "-"
+        )
+        if show_activity:
+            print(f"{agent.nick:<30} {status:<12} {str(pid or '-'):<10} {activity}")
+        else:
+            print(f"{agent.nick:<30} {status:<12} {str(pid or '-'):<10}")
+
+
+def _load_bot_configs() -> list:
+    """Load all valid bot configs from the bots directory."""
+    from culture.bots.config import BOTS_DIR, load_bot_config
+
+    if not BOTS_DIR.is_dir():
+        return []
+    configs = []
+    for bot_dir in sorted(BOTS_DIR.iterdir()):
+        yaml_path = bot_dir / BOT_CONFIG_FILE
+        if not yaml_path.is_file():
+            continue
+        try:
+            configs.append(load_bot_config(yaml_path))
+        except Exception as exc:
+            logger.warning("Failed to load bot config %s: %s", yaml_path, exc)
+    return configs
+
+
+def print_bot_listing() -> None:
+    """Print a table of configured bots (if any exist)."""
+    bot_configs = _load_bot_configs()
+    if not bot_configs:
+        return
+    print()
+    print(f"{'BOT':<30} {'TRIGGER':<12} {'CHANNELS'}")
+    print("-" * 60)
+    for bc in bot_configs:
+        channels = ", ".join(bc.channels) if bc.channels else "-"
+        print(f"{bc.name:<30} {bc.trigger_type:<12} {channels}")

agentirc_cli-4.3.4/culture/cli/shared/ipc.py

@@ -0,0 +1,68 @@
+"""IPC and observer helpers for culture CLI."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from culture.clients.claude.config import load_config_or_default
+
+
+def agent_socket_path(nick: str) -> str:
+    return os.path.join(
+        os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+        f"culture-{nick}.sock",
+    )
+
+
+async def ipc_request(socket_path: str, msg_type: str, **kwargs) -> dict | None:
+    """Send an IPC request via Unix socket and return the response."""
+    from culture.clients.claude.ipc import decode_message, encode_message, make_request
+
+    try:
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_unix_connection(socket_path),
+            timeout=3.0,
+        )
+    except (ConnectionRefusedError, FileNotFoundError, OSError):
+        return None
+    try:
+        req = make_request(msg_type, **kwargs)
+        writer.write(encode_message(req))
+        await writer.drain()
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + 3.0
+        while True:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                return None
+            data = await asyncio.wait_for(reader.readline(), timeout=remaining)
+            msg = decode_message(data)
+            if msg and msg.get("type") == "response":
+                return msg
+    except (asyncio.TimeoutError, ConnectionError, BrokenPipeError, OSError):
+        return None
+    finally:
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except (ConnectionError, BrokenPipeError, OSError):
+            pass
+
+
+async def ipc_shutdown(socket_path: str) -> bool:
+    """Send a shutdown command via Unix socket IPC."""
+    resp = await ipc_request(socket_path, "shutdown")
+    return resp is not None and resp.get("ok", False)
+
+
+def get_observer(config_path: str):
+    """Create an IRCObserver from the config file."""
+    from culture.observer import IRCObserver
+
+    config = load_config_or_default(config_path)
+    return IRCObserver(
+        host=config.server.host,
+        port=config.server.port,
+        server_name=config.server.name,
+    )