agentirc-cli 0.10.7__tar.gz → 0.11.0__tar.gz

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/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.11.0] - 2026-03-28
+
+
+### Added
+
+- agentirc send command for sending messages to channels and agents
+- agentirc status --full flag and per-agent detailed view
+- agentirc sleep/wake commands with configurable schedule (default 23:00-08:00)
+
+
+### Changed
+
+- Extended IPC protocol with status, pause, and resume handlers
+- Added sleep_start/sleep_end config fields to DaemonConfig
+
 ## [0.10.7] - 2026-03-28
 
 

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/PKG-INFO

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

agentirc_cli-0.11.0/agentirc/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.11.0"

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/agentirc/cli.py

@@ -5,10 +5,13 @@ Subcommands:
     agentirc init                       Register an agent for the current directory
     agentirc start [nick] [--all]       Start agent daemon(s)
     agentirc stop [nick] [--all]        Stop agent daemon(s)
-    agentirc status                     List running agents
+    agentirc status [nick] [--full]     List running agents (--full queries activity)
+    agentirc send <target> <message>    Send a message to a channel or agent
     agentirc read <channel>             Read recent channel messages
     agentirc who <channel>              List channel members
     agentirc channels                   List active channels
+    agentirc sleep [nick] [--all]       Pause agent(s) — stay connected but idle
+    agentirc wake [nick] [--all]        Resume paused agent(s)
 """
 from __future__ import annotations
 
@@ -115,6 +118,8 @@ def main() -> None:
 
     # -- status subcommand -------------------------------------------------
     status_parser = sub.add_parser("status", help="List running agents")
+    status_parser.add_argument("nick", nargs="?", help="Show detailed status for a specific agent")
+    status_parser.add_argument("--full", action="store_true", help="Query agents for activity status")
     status_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
 
     # -- read subcommand ---------------------------------------------------
@@ -128,10 +133,28 @@ def main() -> None:
     who_parser.add_argument("channel", help="Channel or nick target")
     who_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
 
+    # -- send subcommand ---------------------------------------------------
+    send_parser = sub.add_parser("send", help="Send a message to a channel or agent")
+    send_parser.add_argument("target", help="Channel (e.g. #general) or agent nick")
+    send_parser.add_argument("message", help="Message text to send")
+    send_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
+
     # -- channels subcommand -----------------------------------------------
     channels_parser = sub.add_parser("channels", help="List active channels")
     channels_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
 
+    # -- sleep subcommand --------------------------------------------------
+    sleep_parser = sub.add_parser("sleep", help="Pause agent(s) — stay connected but idle")
+    sleep_parser.add_argument("nick", nargs="?", help="Agent nick to pause")
+    sleep_parser.add_argument("--all", action="store_true", help="Pause all agents")
+    sleep_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
+
+    # -- wake subcommand ---------------------------------------------------
+    wake_parser = sub.add_parser("wake", help="Resume paused agent(s)")
+    wake_parser.add_argument("nick", nargs="?", help="Agent nick to resume")
+    wake_parser.add_argument("--all", action="store_true", help="Resume all agents")
+    wake_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
+
     # -- skills subcommand -------------------------------------------------
     skills_parser = sub.add_parser("skills", help="Install IRC skills for AI agents")
     skills_sub = skills_parser.add_subparsers(dest="skills_command")
@@ -159,9 +182,12 @@ def main() -> None:
             "start": _cmd_start,
             "stop": _cmd_stop,
             "status": _cmd_status,
+            "send": _cmd_send,
             "read": _cmd_read,
             "who": _cmd_who,
             "channels": _cmd_channels,
+            "sleep": _cmd_sleep,
+            "wake": _cmd_wake,
             "skills": _cmd_skills,
         }
         handler = dispatch.get(args.command)
@@ -652,21 +678,33 @@ def _stop_agent(nick: str) -> None:
     print(f"Agent '{nick}' killed")
 
 
-async def _ipc_shutdown(socket_path: str) -> bool:
-    """Send a shutdown command via Unix socket IPC."""
+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 agentirc.clients.claude.ipc import decode_message, encode_message, make_request
 
-    reader, writer = await asyncio.wait_for(
-        asyncio.open_unix_connection(socket_path),
-        timeout=3.0,
-    )
     try:
-        req = make_request("shutdown")
+        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()
-        data = await asyncio.wait_for(reader.readline(), timeout=3.0)
-        resp = decode_message(data)
-        return resp is not None and resp.get("ok", False)
+        # Read lines until we get a response (skip whispers)
+        deadline = asyncio.get_event_loop().time() + 3.0
+        while True:
+            remaining = deadline - asyncio.get_event_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:
@@ -675,10 +713,37 @@ async def _ipc_shutdown(socket_path: str) -> bool:
             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)
+
+
 # -----------------------------------------------------------------------
 # Agent status
 # -----------------------------------------------------------------------
 
+def _agent_socket_path(nick: str) -> str:
+    return os.path.join(
+        os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+        f"agentirc-{nick}.sock",
+    )
+
+
+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 _cmd_status(args: argparse.Namespace) -> None:
     config = load_config_or_default(args.config)
 
@@ -686,30 +751,64 @@ def _cmd_status(args: argparse.Namespace) -> None:
         print("No agents configured")
         return
 
-    print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10}")
-    print("-" * 52)
+    # Single agent detailed view
+    if args.nick:
+        agent = None
+        for a in config.agents:
+            if a.nick == args.nick:
+                agent = a
+                break
+        if not agent:
+            print(f"Agent '{args.nick}' not found in config", file=sys.stderr)
+            sys.exit(1)
+
+        status, pid = _agent_process_status(agent)
+        print(agent.nick)
+        print(f"  Status:     {status}")
+        print(f"  PID:        {pid or '-'}")
+
+        # Query IPC for activity if running
+        if status == "running":
+            resp = asyncio.run(_ipc_request(_agent_socket_path(agent.nick), "status"))
+            if resp and resp.get("ok"):
+                data = resp.get("data", {})
+                print(f"  Activity:   {data.get('activity', 'unknown')}")
+                print(f"  Turns:      {data.get('turn_count', 0)}")
+                print(f"  Paused:     {'yes' if data.get('paused') else 'no'}")
+        else:
+            print(f"  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:     {args.config}")
+        return
+
+    # All agents view
+    show_activity = args.full
+
+    if show_activity:
+        print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10} {'ACTIVITY':<10}")
+        print("-" * 62)
+    else:
+        print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10}")
+        print("-" * 52)
 
     for agent in config.agents:
-        pid_name = f"agent-{agent.nick}"
-        pid = read_pid(pid_name)
-        status = "stopped"
-
-        if pid and is_process_alive(pid):
-            # Also check if socket is connectable
-            socket_path = os.path.join(
-                os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
-                f"agentirc-{agent.nick}.sock",
-            )
-            if os.path.exists(socket_path):
-                status = "running"
-            else:
-                status = "starting"
-            print(f"{agent.nick:<30} {status:<12} {pid:<10}")
-        elif pid:
-            remove_pid(pid_name)
-            print(f"{agent.nick:<30} {'stopped':<12} {'-':<10}")
+        status, pid = _agent_process_status(agent)
+        activity = "-"
+
+        if show_activity and status == "running":
+            resp = asyncio.run(_ipc_request(_agent_socket_path(agent.nick), "status"))
+            if resp and resp.get("ok"):
+                activity = resp.get("data", {}).get("activity", "unknown")
+
+        if show_activity:
+            print(f"{agent.nick:<30} {status:<12} {str(pid or '-'):<10} {activity:<10}")
         else:
-            print(f"{agent.nick:<30} {'stopped':<12} {'-':<10}")
+            print(f"{agent.nick:<30} {status:<12} {str(pid or '-'):<10}")
 
 
 # -----------------------------------------------------------------------
@@ -728,6 +827,52 @@ def _get_observer(config_path: str):
     )
 
 
+def _ipc_to_agents(args: argparse.Namespace, msg_type: str, action_verb: str) -> None:
+    """Send an IPC message (pause/resume) to one or all agents."""
+    config = load_config_or_default(args.config)
+
+    if args.nick and args.all:
+        print(f"Cannot specify both nick and --all", file=sys.stderr)
+        sys.exit(1)
+
+    if not args.nick and not args.all:
+        print(f"Usage: agentirc {action_verb} <nick> or --all", file=sys.stderr)
+        sys.exit(1)
+
+    targets = config.agents if args.all else []
+    if args.nick:
+        for a in config.agents:
+            if a.nick == args.nick:
+                targets = [a]
+                break
+        else:
+            print(f"Agent '{args.nick}' not found in config", file=sys.stderr)
+            sys.exit(1)
+
+    for agent in targets:
+        socket_path = _agent_socket_path(agent.nick)
+        resp = asyncio.run(_ipc_request(socket_path, msg_type))
+        if resp and resp.get("ok"):
+            print(f"{agent.nick}: {action_verb}")
+        else:
+            print(f"{agent.nick}: failed (not running?)", file=sys.stderr)
+
+
+def _cmd_sleep(args: argparse.Namespace) -> None:
+    _ipc_to_agents(args, "pause", "paused")
+
+
+def _cmd_wake(args: argparse.Namespace) -> None:
+    _ipc_to_agents(args, "resume", "resumed")
+
+
+def _cmd_send(args: argparse.Namespace) -> None:
+    observer = _get_observer(args.config)
+    target = args.target if args.target.startswith("#") else args.target
+    asyncio.run(observer.send_message(target, args.message))
+    print(f"Sent to {target}")
+
+
 def _cmd_read(args: argparse.Namespace) -> None:
     observer = _get_observer(args.config)
     channel = args.channel if args.channel.startswith("#") else f"#{args.channel}"

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/agentirc/clients/claude/config.py

@@ -56,6 +56,8 @@ class DaemonConfig:
     supervisor: SupervisorConfig = field(default_factory=SupervisorConfig)
     webhooks: WebhookConfig = field(default_factory=WebhookConfig)
     buffer_size: int = 500
+    sleep_start: str = "23:00"
+    sleep_end: str = "08:00"
     agents: list[AgentConfig] = field(default_factory=list)
 
     def get_agent(self, nick: str) -> AgentConfig | None:
@@ -84,6 +86,8 @@ def load_config(path: str | Path) -> DaemonConfig:
         supervisor=supervisor,
         webhooks=webhooks,
         buffer_size=raw.get("buffer_size", 500),
+        sleep_start=raw.get("sleep_start", "23:00"),
+        sleep_end=raw.get("sleep_end", "08:00"),
         agents=agents,
     )
 

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/agentirc/clients/claude/daemon.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import datetime
 import logging
 import os
 import time
@@ -53,6 +54,10 @@ class AgentDaemon:
         self._crash_times: list[float] = []
         self._circuit_open = False
 
+        # Pause/sleep state
+        self._paused: bool = False
+        self._last_activation: float | None = None
+
         # Graceful shutdown
         self._stop_event: asyncio.Event | None = None
         self._pid_name: str = ""
@@ -112,12 +117,23 @@ class AgentDaemon:
         if not self.skip_claude:
             await self._start_agent_runner()
 
+        # 7. Sleep scheduler background task
+        self._sleep_task = asyncio.create_task(self._sleep_scheduler())
+
         logger.info(
             "AgentDaemon started for %s (socket=%s)", self.agent.nick, self._socket_path
         )
 
     async def stop(self) -> None:
         """Cleanly shut down all components."""
+        if hasattr(self, "_sleep_task") and self._sleep_task:
+            self._sleep_task.cancel()
+            try:
+                await self._sleep_task
+            except asyncio.CancelledError:
+                pass
+            self._sleep_task = None
+
         if self._agent_runner is not None:
             await self._agent_runner.stop()
             self._agent_runner = None
@@ -136,6 +152,54 @@ class AgentDaemon:
 
         logger.info("AgentDaemon stopped for %s", self.agent.nick)
 
+    def _parse_sleep_schedule(self) -> tuple[int, int] | None:
+        """Parse sleep_start/sleep_end into minutes. Returns None if invalid."""
+        try:
+            sh, sm = (int(x) for x in self.config.sleep_start.split(":"))
+            wh, wm = (int(x) for x in self.config.sleep_end.split(":"))
+            if not (0 <= sh <= 23 and 0 <= sm <= 59 and 0 <= wh <= 23 and 0 <= wm <= 59):
+                raise ValueError("hours/minutes out of range")
+            return (sh * 60 + sm, wh * 60 + wm)
+        except (ValueError, AttributeError):
+            logger.warning(
+                "Invalid sleep schedule '%s'-'%s' for %s — scheduler disabled",
+                getattr(self.config, "sleep_start", None),
+                getattr(self.config, "sleep_end", None),
+                self.agent.nick,
+            )
+            return None
+
+    async def _sleep_scheduler(self) -> None:
+        """Background task that auto-pauses/resumes based on sleep schedule."""
+        schedule = self._parse_sleep_schedule()
+        if schedule is None:
+            return
+        sleep_minutes, wake_minutes = schedule
+
+        while True:
+            try:
+                await asyncio.sleep(60)  # Check every minute
+                now = datetime.datetime.now()
+                current_minutes = now.hour * 60 + now.minute
+
+                if sleep_minutes > wake_minutes:
+                    # Overnight: e.g., 23:00-08:00
+                    should_sleep = current_minutes >= sleep_minutes or current_minutes < wake_minutes
+                else:
+                    # Same day: e.g., 13:00-14:00
+                    should_sleep = sleep_minutes <= current_minutes < wake_minutes
+
+                if should_sleep and not self._paused:
+                    self._paused = True
+                    logger.info("Sleep schedule: pausing %s", self.agent.nick)
+                elif not should_sleep and self._paused:
+                    self._paused = False
+                    logger.info("Sleep schedule: resuming %s", self.agent.nick)
+            except asyncio.CancelledError:
+                return
+            except Exception:
+                logger.exception("Sleep scheduler error")
+
     async def _graceful_shutdown(self) -> None:
         """Trigger a graceful shutdown, signaling any waiting stop event."""
         logger.info("Graceful shutdown requested for %s", self.agent.nick)
@@ -169,7 +233,10 @@ class AgentDaemon:
 
         Formats a prompt and enqueues it so the SDK session picks it up.
         """
+        if self._paused:
+            return
         if self._agent_runner and self._agent_runner.is_running():
+            self._last_activation = time.time()
             if target.startswith("#"):
                 prompt = f"[IRC @mention in {target}] <{sender}> {text}"
             else:
@@ -305,6 +372,15 @@ class AgentDaemon:
             elif msg_type == "clear":
                 return await self._ipc_clear(req_id)
 
+            elif msg_type == "status":
+                return self._ipc_status(req_id)
+
+            elif msg_type == "pause":
+                return await self._ipc_pause(req_id)
+
+            elif msg_type == "resume":
+                return await self._ipc_resume(req_id)
+
             elif msg_type == "shutdown":
                 asyncio.create_task(self._graceful_shutdown())
                 return make_response(req_id, ok=True)
@@ -320,6 +396,30 @@ class AgentDaemon:
     # IPC sub-handlers
     # ------------------------------------------------------------------
 
+    async def _ipc_pause(self, req_id: str) -> dict:
+        self._paused = True
+        logger.info("Agent %s paused", self.agent.nick)
+        return make_response(req_id, ok=True)
+
+    async def _ipc_resume(self, req_id: str) -> dict:
+        self._paused = False
+        logger.info("Agent %s resumed", self.agent.nick)
+        # NOTE: Catch-up on missed messages is not yet implemented.
+        # IRCTransport does not process HISTORY responses into the buffer.
+        # The agent resumes and will see new messages going forward.
+        return make_response(req_id, ok=True)
+
+    def _ipc_status(self, req_id: str) -> dict:
+        running = self._agent_runner is not None and self._agent_runner.is_running()
+        turn_count = self._supervisor._turn_count if self._supervisor else 0
+        return make_response(req_id, ok=True, data={
+            "running": running,
+            "paused": self._paused,
+            "turn_count": turn_count,
+            "last_activation": self._last_activation,
+            "activity": "paused" if self._paused else ("working" if running else "idle"),
+        })
+
     async def _ipc_irc_send(self, req_id: str, msg: dict) -> dict:
         channel = msg.get("channel", "")
         text = msg.get("message", "")

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/agentirc/clients/claude/irc_transport.py

@@ -82,11 +82,15 @@ class IRCTransport:
     async def send_who(self, target: str) -> None:
         await self._send_raw(f"WHO {target}")
 
-    async def _send_raw(self, line: str) -> None:
+    async def send_raw(self, line: str) -> None:
+        """Send a raw IRC line. Public for commands like HISTORY."""
         if self._writer:
             self._writer.write(f"{line}\r\n".encode())
             await self._writer.drain()
 
+    async def _send_raw(self, line: str) -> None:
+        await self.send_raw(line)
+
     async def _read_loop(self) -> None:
         buf = ""
         try:

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/agentirc/observer.py

@@ -188,6 +188,29 @@ class IRCObserver:
         finally:
             await self._disconnect(writer)
 
+    async def send_message(self, target: str, text: str) -> None:
+        """Send a PRIVMSG to a channel or nick, then disconnect.
+
+        Uses the same ephemeral connection pattern as the read commands.
+        """
+        # Sanitize CR/LF to prevent IRC command injection
+        target = target.replace("\r", "").replace("\n", "")
+        text = text.replace("\r", "").replace("\n", " ")
+
+        reader, writer, nick = await self._connect_and_register()
+        try:
+            # If sending to a channel, join it first so the server accepts the PRIVMSG
+            if target.startswith("#"):
+                writer.write(f"JOIN {target}\r\n".encode())
+                await writer.drain()
+                # Drain join responses
+                await self._recv_lines(reader, timeout=1.0)
+
+            writer.write(f"PRIVMSG {target} :{text}\r\n".encode())
+            await writer.drain()
+        finally:
+            await self._disconnect(writer)
+
     async def list_channels(self) -> list[str]:
         """List active channels using the LIST command.
 

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/docs/cli.md

@@ -107,13 +107,58 @@ Sends shutdown via IPC socket, falls back to PID file + SIGTERM.
 List all configured agents and their running state.
 
 ```bash
-agentirc status
+agentirc status                    # quick view (nick, status, PID)
+agentirc status --full             # query running agents for activity
+agentirc status spark-agentirc     # detailed view for one agent
+```
+
+| Flag | Description |
+|------|-------------|
+| `--full` | Query each running agent via IPC for activity status |
+| `nick` | Show detailed single-agent view (directory, backend, model, etc.) |
+
+### `agentirc sleep`
+
+Pause agent(s) — daemon stays connected to IRC but ignores @mentions.
+
+```bash
+agentirc sleep spark-agentirc     # pause specific agent
+agentirc sleep --all              # pause all agents
+```
+
+Agents auto-pause at `sleep_start` (default `23:00`) and auto-resume at `sleep_end` (default `08:00`). Configure in `agents.yaml`:
+
+```yaml
+sleep_start: "23:00"
+sleep_end: "08:00"
+```
+
+### `agentirc wake`
+
+Resume paused agent(s).
+
+```bash
+agentirc wake spark-agentirc      # resume specific agent
+agentirc wake --all               # resume all agents
 ```
 
 ## Observation
 
 Read-only commands for peeking at the network. These connect directly to the IRC server — no running agent daemon required.
 
+### `agentirc send`
+
+Send a message to a channel or agent.
+
+```bash
+agentirc send "#general" "hello from the CLI"
+agentirc send spark-agentirc "what are you working on?"
+```
+
+Uses an ephemeral IRC connection — no daemon required.
+
+Read-only commands for peeking at the network. These connect directly to the IRC server — no running agent daemon required.
+
 ### `agentirc read`
 
 Read recent channel messages.

{agentirc_cli-0.10.7 → agentirc_cli-0.11.0}/pyproject.toml

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