agentirc-cli 0.12.1__tar.gz → 0.13.0__tar.gz

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.13.0] - 2026-03-29
+
+### Added
+
+- `system_prompt` field in AgentConfig — custom system prompt via agents.yaml (all backends)
+- `prompt_override` field in SupervisorConfig — custom supervisor eval prompt via config (all backends)
+- Status/pause/resume IPC handlers for OpenCode, Codex, and Copilot daemons (parity with Claude)
+- Sleep scheduler with `sleep_start`/`sleep_end` config for OpenCode, Codex, and Copilot
+- Null relay target fix in `_query_agent_status()` to prevent misrouting
+
 ## [0.12.1] - 2026-03-29
 
 

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/PKG-INFO

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

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

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/agentirc/clients/claude/config.py

@@ -25,6 +25,7 @@ class SupervisorConfig:
     window_size: int = 20
     eval_interval: int = 5
     escalation_threshold: int = 3
+    prompt_override: str = ""
 
 
 @dataclass
@@ -47,6 +48,7 @@ class AgentConfig:
     channels: list[str] = field(default_factory=lambda: ["#general"])
     model: str = "claude-opus-4-6"
     thinking: str = "medium"
+    system_prompt: str = ""
 
 
 @dataclass

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/agentirc/clients/claude/daemon.py

@@ -113,6 +113,7 @@ class AgentDaemon:
             evaluate_fn=make_sdk_evaluate_fn(
                 model=self.config.supervisor.model,
                 thinking=self.config.supervisor.thinking,
+                prompt_override=self.config.supervisor.prompt_override,
             ),
             on_whisper=self._on_supervisor_whisper,
             on_escalation=self._on_supervisor_escalation,
@@ -269,6 +270,8 @@ class AgentDaemon:
                 self._status_query_event.set()
 
     def _build_system_prompt(self) -> str:
+        if self.agent.system_prompt:
+            return self.agent.system_prompt
         return (
             f"You are {self.agent.nick}, an AI agent on the agentirc IRC network.\n"
             f"You have IRC tools available via the irc skill. Use them to communicate.\n"

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/agentirc/clients/claude/supervisor.py

@@ -115,8 +115,10 @@ def _format_window(window: list[dict[str, Any]], task: str) -> str:
 def make_sdk_evaluate_fn(
     model: str = "claude-sonnet-4-6",
     thinking: str | None = None,
+    prompt_override: str = "",
 ) -> EvaluateFn:
     """Create an evaluate_fn that uses the Claude Agent SDK."""
+    system_prompt = prompt_override or _SUPERVISOR_SYSTEM_PROMPT
 
     async def evaluate(window: list[dict[str, Any]], task: str) -> SupervisorVerdict:
         prompt = _format_window(window, task)
@@ -124,7 +126,7 @@ def make_sdk_evaluate_fn(
         opts = ClaudeAgentOptions(
             model=model,
             max_turns=1,
-            system_prompt=_SUPERVISOR_SYSTEM_PROMPT,
+            system_prompt=system_prompt,
             tools=[],
         )
         if thinking:

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/agentirc/clients/codex/config.py

@@ -24,6 +24,7 @@ class SupervisorConfig:
     window_size: int = 20
     eval_interval: int = 5
     escalation_threshold: int = 3
+    prompt_override: str = ""
 
 
 @dataclass
@@ -45,6 +46,7 @@ class AgentConfig:
     directory: str = "."
     channels: list[str] = field(default_factory=lambda: ["#general"])
     model: str = "gpt-5.4"
+    system_prompt: str = ""
 
 
 @dataclass
@@ -54,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:
@@ -82,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.12.1 → agentirc_cli-0.13.0}/agentirc/clients/codex/daemon.py

@@ -7,6 +7,7 @@ CodexSupervisor (codex exec for periodic evaluation).
 from __future__ import annotations
 
 import asyncio
+import datetime
 import logging
 import os
 import time
@@ -66,6 +67,15 @@ class CodexDaemon:
         self._crash_times: list[float] = []
         self._circuit_open = False
 
+        # Pause/sleep state
+        self._paused: bool = False
+        self._last_activation: float | None = None
+
+        # Status query state — for asking the agent what it's doing
+        self._status_query_event: asyncio.Event | None = None
+        self._status_query_response: str = ""
+        self._last_activity_text: str = ""
+
         # Graceful shutdown
         self._stop_event: asyncio.Event | None = None
         self._pid_name: str = ""
@@ -114,6 +124,7 @@ class CodexDaemon:
             window_size=self.config.supervisor.window_size,
             eval_interval=self.config.supervisor.eval_interval,
             escalation_threshold=self.config.supervisor.escalation_threshold,
+            prompt_override=self.config.supervisor.prompt_override,
             on_whisper=self._on_supervisor_whisper,
             on_escalation=self._on_supervisor_escalation,
         )
@@ -122,12 +133,23 @@ class CodexDaemon:
         if not self.skip_codex:
             await self._start_agent_runner()
 
+        # 7. Sleep scheduler background task
+        self._sleep_task = asyncio.create_task(self._sleep_scheduler())
+
         logger.info(
             "CodexDaemon 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
@@ -146,6 +168,54 @@ class CodexDaemon:
 
         logger.info("CodexDaemon 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)
@@ -179,7 +249,10 @@ class CodexDaemon:
 
         Formats a prompt and enqueues it so the Codex session picks it up.
         """
+        if self._paused:
+            return
         if self._agent_runner and self._agent_runner.is_running():
+            self._last_activation = time.time()
             # Enqueue relay target (FIFO matches prompt queue order)
             self._mention_targets.append(target if target.startswith("#") else sender)
             if target.startswith("#"):
@@ -209,7 +282,24 @@ class CodexDaemon:
         if self._supervisor:
             await self._supervisor.observe(msg)
 
+        # Capture last assistant text for status reporting
+        if msg.get("type") == "assistant":
+            for block in msg.get("content", []):
+                if isinstance(block, dict) and block.get("type") == "text":
+                    self._last_activity_text = block["text"]
+                    break
+                elif isinstance(block, str):
+                    self._last_activity_text = block
+                    break
+
+            # If a status query is pending, fulfill it
+            if self._status_query_event and not self._status_query_event.is_set():
+                self._status_query_response = self._last_activity_text
+                self._status_query_event.set()
+
     def _build_system_prompt(self) -> str:
+        if self.agent.system_prompt:
+            return self.agent.system_prompt
         return (
             f"You are {self.agent.nick}, an AI agent on the agentirc IRC network.\n"
             f"You have IRC tools available via the irc skill. Use them to communicate.\n"
@@ -333,6 +423,15 @@ class CodexDaemon:
             elif msg_type == "clear":
                 return await self._ipc_clear(req_id)
 
+            elif msg_type == "status":
+                return await self._ipc_status(req_id, msg)
+
+            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)
@@ -348,6 +447,82 @@ class CodexDaemon:
     # 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)
+
+    async def _ipc_status(self, req_id: str, msg: dict | None = None) -> 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
+
+        # Determine activity description
+        query = msg.get("query", False) if msg else False
+        description = self._describe_activity(live_query=query)
+
+        # If live query requested and agent is active, ask the agent directly
+        if query and running and not self._paused:
+            description = await self._query_agent_status()
+
+        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"),
+            "description": description,
+        })
+
+    def _describe_activity(self, live_query: bool = False) -> str:
+        """Return a human-readable description of what the agent is doing."""
+        if self._paused:
+            return "paused"
+        if not self._last_activity_text:
+            return "nothing"
+        # Return first line of last activity, truncated
+        first_line = self._last_activity_text.strip().split("\n")[0]
+        if len(first_line) > 120:
+            first_line = first_line[:117] + "..."
+        return first_line
+
+    async def _query_agent_status(self) -> str:
+        """Ask the agent directly what it's working on."""
+        if not self._agent_runner or not self._agent_runner.is_running():
+            return "nothing"
+
+        self._status_query_event = asyncio.Event()
+        self._status_query_response = ""
+
+        try:
+            # Enqueue a None relay target so the status response doesn't
+            # steal a real mention's relay target from the deque.
+            self._mention_targets.append(None)
+            await self._agent_runner.send_prompt(
+                "[SYSTEM] Briefly describe what you are currently working on "
+                "in one sentence. Reply with just the description, no preamble."
+            )
+            # Wait up to 10s for the agent to respond
+            await asyncio.wait_for(self._status_query_event.wait(), timeout=10.0)
+            response = self._status_query_response.strip()
+            # Take first line, truncate
+            first_line = response.split("\n")[0]
+            if len(first_line) > 120:
+                first_line = first_line[:117] + "..."
+            return first_line or "nothing"
+        except asyncio.TimeoutError:
+            return "busy (no response)"
+        finally:
+            self._status_query_event = None
+            self._status_query_response = ""
+
     async def _ipc_irc_send(self, req_id: str, msg: dict) -> dict:
         channel = msg.get("channel", "")
         text = msg.get("message", "")

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/agentirc/clients/codex/supervisor.py

@@ -51,6 +51,7 @@ class CodexSupervisor:
         window_size: int = 20,
         eval_interval: int = 5,
         escalation_threshold: int = 3,
+        prompt_override: str = "",
         on_whisper: Callable[[str, str], Awaitable[None]] | None = None,
         on_escalation: Callable[[str], Awaitable[None]] | None = None,
     ):
@@ -58,6 +59,7 @@ class CodexSupervisor:
         self.window_size = window_size
         self.eval_interval = eval_interval
         self.escalation_threshold = escalation_threshold
+        self.prompt_override = prompt_override
         self.on_whisper = on_whisper
         self.on_escalation = on_escalation
 
@@ -86,7 +88,14 @@ class CodexSupervisor:
     async def _evaluate(self) -> None:
         """Run codex exec to evaluate the agent's recent activity."""
         transcript = self._format_transcript()
-        prompt = SUPERVISOR_PROMPT.format(transcript=transcript)
+        template = self.prompt_override or SUPERVISOR_PROMPT
+        try:
+            prompt = template.format(transcript=transcript)
+        except (KeyError, IndexError, ValueError) as exc:
+            logger.warning(
+                "Invalid prompt_override template, falling back to default: %s", exc
+            )
+            prompt = SUPERVISOR_PROMPT.format(transcript=transcript)
 
         # Isolate from host config (~/.codex/, XDG, etc.)
         isolated_home = tempfile.mkdtemp(prefix="agentirc-codex-sv-")

{agentirc_cli-0.12.1 → agentirc_cli-0.13.0}/agentirc/clients/copilot/config.py

@@ -24,6 +24,7 @@ class SupervisorConfig:
     window_size: int = 20
     eval_interval: int = 5
     escalation_threshold: int = 3
+    prompt_override: str = ""
 
 
 @dataclass
@@ -45,6 +46,7 @@ class AgentConfig:
     directory: str = "."
     channels: list[str] = field(default_factory=lambda: ["#general"])
     model: str = "gpt-4.1"
+    system_prompt: str = ""
 
 
 @dataclass
@@ -54,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:
@@ -82,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.12.1 → agentirc_cli-0.13.0}/agentirc/clients/copilot/daemon.py

@@ -7,6 +7,7 @@ CopilotSupervisor (Copilot SDK for periodic evaluation).
 from __future__ import annotations
 
 import asyncio
+import datetime
 import logging
 import os
 import time
@@ -66,6 +67,15 @@ class CopilotDaemon:
         self._crash_times: list[float] = []
         self._circuit_open = False
 
+        # Pause/sleep state
+        self._paused: bool = False
+        self._last_activation: float | None = None
+
+        # Status query state — for asking the agent what it's doing
+        self._status_query_event: asyncio.Event | None = None
+        self._status_query_response: str = ""
+        self._last_activity_text: str = ""
+
         # Graceful shutdown
         self._stop_event: asyncio.Event | None = None
         self._pid_name: str = ""
@@ -116,18 +126,30 @@ class CopilotDaemon:
             escalation_threshold=self.config.supervisor.escalation_threshold,
             on_whisper=self._on_supervisor_whisper,
             on_escalation=self._on_supervisor_escalation,
+            prompt_override=self.config.supervisor.prompt_override,
         )
 
         # 6. Optionally start the Copilot agent runner
         if not self.skip_copilot:
             await self._start_agent_runner()
 
+        # 7. Sleep scheduler background task
+        self._sleep_task = asyncio.create_task(self._sleep_scheduler())
+
         logger.info(
             "CopilotDaemon 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
@@ -146,6 +168,54 @@ class CopilotDaemon:
 
         logger.info("CopilotDaemon 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)
@@ -186,7 +256,10 @@ class CopilotDaemon:
 
         Formats a prompt and enqueues it so the Copilot session picks it up.
         """
+        if self._paused:
+            return
         if self._agent_runner and self._agent_runner.is_running():
+            self._last_activation = time.time()
             # Enqueue relay target (FIFO matches prompt queue order)
             self._mention_targets.append(target if target.startswith("#") else sender)
             if target.startswith("#"):
@@ -216,7 +289,24 @@ class CopilotDaemon:
         if self._supervisor:
             await self._supervisor.observe(msg)
 
+        # Capture last assistant text for status reporting
+        if msg.get("type") == "assistant":
+            for block in msg.get("content", []):
+                if isinstance(block, dict) and block.get("type") == "text":
+                    self._last_activity_text = block["text"]
+                    break
+                elif isinstance(block, str):
+                    self._last_activity_text = block
+                    break
+
+            # If a status query is pending, fulfill it
+            if self._status_query_event and not self._status_query_event.is_set():
+                self._status_query_response = self._last_activity_text
+                self._status_query_event.set()
+
     def _build_system_prompt(self) -> str:
+        if self.agent.system_prompt:
+            return self.agent.system_prompt
         return (
             f"You are {self.agent.nick}, an AI agent on the agentirc IRC network.\n"
             f"You have IRC tools available via the irc skill. Use them to communicate.\n"
@@ -340,6 +430,15 @@ class CopilotDaemon:
             elif msg_type == "clear":
                 return await self._ipc_clear(req_id)
 
+            elif msg_type == "status":
+                return await self._ipc_status(req_id, msg)
+
+            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)
@@ -355,6 +454,82 @@ class CopilotDaemon:
     # 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)
+
+    async def _ipc_status(self, req_id: str, msg: dict | None = None) -> 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
+
+        # Determine activity description
+        query = msg.get("query", False) if msg else False
+        description = self._describe_activity(live_query=query)
+
+        # If live query requested and agent is active, ask the agent directly
+        if query and running and not self._paused:
+            description = await self._query_agent_status()
+
+        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"),
+            "description": description,
+        })
+
+    def _describe_activity(self, live_query: bool = False) -> str:
+        """Return a human-readable description of what the agent is doing."""
+        if self._paused:
+            return "paused"
+        if not self._last_activity_text:
+            return "nothing"
+        # Return first line of last activity, truncated
+        first_line = self._last_activity_text.strip().split("\n")[0]
+        if len(first_line) > 120:
+            first_line = first_line[:117] + "..."
+        return first_line
+
+    async def _query_agent_status(self) -> str:
+        """Ask the agent directly what it's working on."""
+        if not self._agent_runner or not self._agent_runner.is_running():
+            return "nothing"
+
+        self._status_query_event = asyncio.Event()
+        self._status_query_response = ""
+
+        try:
+            # Enqueue a None relay target so the status response doesn't
+            # steal a real mention's relay target from the deque.
+            self._mention_targets.append(None)
+            await self._agent_runner.send_prompt(
+                "[SYSTEM] Briefly describe what you are currently working on "
+                "in one sentence. Reply with just the description, no preamble."
+            )
+            # Wait up to 10s for the agent to respond
+            await asyncio.wait_for(self._status_query_event.wait(), timeout=10.0)
+            response = self._status_query_response.strip()
+            # Take first line, truncate
+            first_line = response.split("\n")[0]
+            if len(first_line) > 120:
+                first_line = first_line[:117] + "..."
+            return first_line or "nothing"
+        except asyncio.TimeoutError:
+            return "busy (no response)"
+        finally:
+            self._status_query_event = None
+            self._status_query_response = ""
+
     async def _ipc_irc_send(self, req_id: str, msg: dict) -> dict:
         channel = msg.get("channel", "")
         text = msg.get("message", "")