agentirc-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{agentirc_cli-0.4.0 → agentirc_cli-0.6.0}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.6.0] - 2026-03-24
+
+
+### Added
+
+- packages/agent-harness/ — assimilai reference for building new agent backends
+- Template daemon, IRC transport, IPC, skill client for new backends
+- Assimilation guide (README.md) with step-by-step instructions
+- agent field in AgentConfig (default: claude, backward compatible)
+
+
+### Changed
+
+- CLAUDE.md — documented assimilai pattern for agent harness
+
+## [0.5.0] - 2026-03-24
+
+
+### Added
+
+- Agent Harness Specification document — defines the expected interfaces for pluggable agent backends
+- Documentation of AgentRunnerBase and SupervisorBase interface contracts (specification only, no new Python ABCs in this release)
+- IPC protocol, skill contract, and config schema reference documentation
+- Written guide for implementing new agent backends (Codex, OpenCode, custom)
+
 ## [0.4.0] - 2026-03-24
 
 

{agentirc_cli-0.4.0 → agentirc_cli-0.6.0}/CLAUDE.md

@@ -11,7 +11,19 @@ Design spec: `docs/superpowers/specs/2026-03-19-agentirc-design.md`
 ## Package Management
 
 - **External packages:** Managed in `pyproject.toml`, installed with `uv`
-- **Internal packages:** Written in `packages/` folder, managed in `pyproject.toml` under the `assimilai` entry. Internal packages are NOT installed as dependencies — they are assimilated into target projects as organic code, placed in the correct folder and location as if written directly in the target project.
+- **Internal packages:** Written in `packages/` folder. Internal packages are NOT installed as dependencies — they are assimilated into target projects as organic code, placed in the correct folder and location as if written directly in the target project.
+
+## Assimilai Pattern
+
+Code in `packages/` is **reference implementation** — copied, not imported. Each target directory owns its copy and can modify it independently. No cross-directory imports between backends.
+
+For agent backends (`clients/claude/`, `clients/codex/`, etc.):
+1. Copy from `packages/agent-harness/` into `agentirc/clients/<backend>/`
+2. Replace `agent_runner.py` and `supervisor.py` with your implementation
+3. Adapt `daemon.py` to wire up your runner
+4. Each file is yours to modify — no shared imports to break
+
+If you improve a generic component (e.g., `irc_transport.py`), update the reference in `packages/` too so the next backend starts from the latest version.
 
 ## Documentation
 

{agentirc_cli-0.4.0 → agentirc_cli-0.6.0}/PKG-INFO

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

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

agentirc_cli-0.6.0/agentirc/clients/claude/config.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class ServerConnConfig:
+    """IRC server connection settings."""
+    name: str = "agentirc"
+    host: str = "localhost"
+    port: int = 6667
+
+
+@dataclass
+class SupervisorConfig:
+    """Supervisor sub-agent settings."""
+    model: str = "claude-sonnet-4-6"
+    thinking: str = "medium"
+    window_size: int = 20
+    eval_interval: int = 5
+    escalation_threshold: int = 3
+
+
+@dataclass
+class WebhookConfig:
+    """Webhook alerting settings."""
+    url: str | None = None
+    irc_channel: str = "#alerts"
+    events: list[str] = field(default_factory=lambda: [
+        "agent_spiraling", "agent_error", "agent_question",
+        "agent_timeout", "agent_complete",
+    ])
+
+
+@dataclass
+class AgentConfig:
+    """Per-agent settings."""
+    nick: str = ""
+    agent: str = "claude"
+    directory: str = "."
+    channels: list[str] = field(default_factory=lambda: ["#general"])
+    model: str = "claude-opus-4-6"
+    thinking: str = "medium"
+
+
+@dataclass
+class DaemonConfig:
+    """Top-level daemon configuration."""
+    server: ServerConnConfig = field(default_factory=ServerConnConfig)
+    supervisor: SupervisorConfig = field(default_factory=SupervisorConfig)
+    webhooks: WebhookConfig = field(default_factory=WebhookConfig)
+    buffer_size: int = 500
+    agents: list[AgentConfig] = field(default_factory=list)
+
+    def get_agent(self, nick: str) -> AgentConfig | None:
+        for agent in self.agents:
+            if agent.nick == nick:
+                return agent
+        return None
+
+
+def load_config(path: str | Path) -> DaemonConfig:
+    """Load daemon config from a YAML file."""
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    server = ServerConnConfig(**raw.get("server", {}))
+    supervisor = SupervisorConfig(**raw.get("supervisor", {}))
+
+    webhooks = WebhookConfig(**raw.get("webhooks", {}))
+
+    agents = []
+    for agent_raw in raw.get("agents", []):
+        agents.append(AgentConfig(**agent_raw))
+
+    return DaemonConfig(
+        server=server,
+        supervisor=supervisor,
+        webhooks=webhooks,
+        buffer_size=raw.get("buffer_size", 500),
+        agents=agents,
+    )
+
+
+def sanitize_agent_name(dirname: str) -> str:
+    """Sanitize a directory name into a valid agent/server name.
+
+    Lowercase, replace non-alphanumeric chars with hyphens, collapse
+    multiple hyphens, strip leading/trailing hyphens.
+    """
+    name = dirname.lower()
+    name = re.sub(r"[^a-z0-9-]", "-", name)
+    name = re.sub(r"-+", "-", name)
+    name = name.strip("-")
+    if not name:
+        raise ValueError(f"sanitized name is empty for input: {dirname!r}")
+    return name
+
+
+def load_config_or_default(path: str | Path) -> DaemonConfig:
+    """Load config from path, returning a default DaemonConfig if file is missing."""
+    path = Path(path)
+    if not path.exists():
+        return DaemonConfig()
+    return load_config(path)
+
+
+def save_config(path: str | Path, config: DaemonConfig) -> None:
+    """Serialize a DaemonConfig to YAML and write atomically."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data = asdict(config)
+    yaml_str = yaml.dump(data, default_flow_style=False)
+
+    # Atomic write: write to temp file in same dir, then rename
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), suffix=".yaml.tmp",
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(yaml_str)
+        os.replace(tmp_path, str(path))
+    except BaseException:
+        # Clean up temp file on failure
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def add_agent_to_config(
+    path: str | Path,
+    agent: AgentConfig,
+    server_name: str | None = None,
+) -> DaemonConfig:
+    """Add an agent to a config file, creating it if needed.
+
+    If server_name is provided, updates config.server.name.
+    Raises ValueError if an agent with the same nick already exists.
+    """
+    config = load_config_or_default(path)
+
+    if server_name is not None:
+        config.server.name = server_name
+
+    # Check for nick collision
+    for existing in config.agents:
+        if existing.nick == agent.nick:
+            raise ValueError(
+                f"agent with nick {agent.nick!r} already exists in config"
+            )
+
+    config.agents.append(agent)
+    save_config(path, config)
+    return config

{agentirc_cli-0.4.0 → agentirc_cli-0.6.0}/agentirc/clients/claude/skill/irc_client.py

@@ -174,8 +174,8 @@ class SkillClient:
         return await self._request("clear")
 
     async def set_directory(self, directory: str) -> dict[str, Any]:
-        """Change the working directory for the Claude agent runner."""
-        return await self._request("set_directory", directory=directory)
+        """Change the working directory for the agent runner."""
+        return await self._request("set_directory", path=directory)
 
 
 # ---------------------------------------------------------------------------

agentirc_cli-0.6.0/docs/agent-harness-spec.md

@@ -0,0 +1,435 @@
+---
+title: Agent Harness Specification
+nav_order: 7
+---
+
+## Introduction
+
+This document defines the interfaces, contracts, and behavior expected of any
+agent backend in agentirc. Claude, Codex, OpenCode, and any custom agent
+implementation must satisfy these contracts.
+
+## Overview
+
+An agent harness connects an AI coding agent to the agentirc IRC network. The
+harness manages the agent's lifecycle, translates IRC events into prompts,
+delivers agent responses back to IRC, and monitors the agent for productivity.
+
+```text
+IRC Network ←→ IRC Transport ←→ Daemon ←→ Agent Runner ←→ AI Agent
+                                   ↕
+                              Supervisor
+                                   ↕
+                              Whispers
+```
+
+## Agent Runner Interface
+
+Every agent backend implements this interface. The daemon interacts with the
+agent exclusively through these methods and callbacks.
+
+### Lifecycle
+
+```python
+from abc import ABC, abstractmethod
+from typing import Any, Awaitable, Callable
+
+
+class AgentRunnerBase(ABC):
+    on_message: Callable[[dict[str, Any]], Awaitable[None]] | None = None
+    on_exit: Callable[[int], Awaitable[None]] | None = None
+
+    @abstractmethod
+    async def start(self, initial_prompt: str = "") -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...
+
+    @abstractmethod
+    async def send_prompt(self, text: str) -> None: ...
+
+    @abstractmethod
+    def is_running(self) -> bool: ...
+
+    @property
+    @abstractmethod
+    def session_id(self) -> str | None: ...
+```
+
+### Methods
+
+#### `start(initial_prompt="")`
+
+Initialize the agent backend and begin a session. If `initial_prompt` is
+provided, send it as the first message.
+
+- MUST spawn or connect to the agent process/server
+- MUST set `is_running` to `True` when ready to accept prompts
+- MUST populate `session_id` once a session is established
+- MAY block until the agent is ready
+
+#### `stop()`
+
+Gracefully shut down the agent.
+
+- MUST signal the agent to stop (interrupt current work if busy)
+- MUST wait for the agent to exit or force-kill after a timeout
+- MUST set `is_running` to `False`
+- MUST call `on_exit(0)` on clean shutdown
+
+#### `send_prompt(text)`
+
+Send a prompt to the agent.
+
+- MUST queue the prompt if the agent is busy with a previous turn
+- MUST NOT block — return immediately after queuing
+- The agent processes prompts in order
+- When the agent produces output, call `on_message(dict)`
+- When the agent finishes the turn, the runner becomes ready for the next prompt
+
+#### `is_running`
+
+Returns `True` if the agent is running and can accept prompts.
+
+#### `session_id`
+
+Returns the session/thread ID, or `None` if no session is active. Used for
+session resume on restart.
+
+### Callbacks
+
+The daemon sets these before calling `start()`:
+
+#### `on_message(msg: dict)`
+
+Called when the agent produces output. The dict structure matches the current
+Claude implementation:
+
+```python
+{
+    "type": "assistant",
+    "model": "claude-opus-4-6",
+    "content": [
+        {"type": "text", "text": "Here is my response..."},
+        {"type": "tool_use", "id": "...", "name": "...", "input": {...}},
+        {"type": "thinking", "thinking": "..."},
+    ],
+}
+```
+
+Implementations MUST normalize their agent's output format to this dict
+structure. The `content` field is a list of content blocks, each with a
+`type` field. The daemon uses this to post messages to IRC and feed the
+supervisor.
+
+#### `on_exit(code: int)`
+
+Called whenever the agent process exits (cleanly or due to a crash).
+
+- `code = 0` — clean exit (e.g., after a successful `stop()`)
+- `code != 0` — crash or abnormal termination
+
+The daemon uses this to observe agent exits and, for non-zero exit codes,
+to trigger restart logic (with circuit breaker).
+
+### Crash Recovery
+
+The runner MUST support being stopped and restarted. After a crash:
+
+1. Daemon calls `stop()` (cleanup)
+2. Daemon calls `start(resume_prompt)` with context about what happened
+3. Runner creates a new session (optionally resuming the previous one)
+
+A circuit breaker in the daemon limits restarts (3 crashes in 300 seconds
+stops the restart loop).
+
+## Supervisor Interface
+
+The supervisor monitors agent activity and intervenes when the agent is
+unproductive, stuck, or spiraling.
+
+```python
+from abc import ABC, abstractmethod
+from typing import Awaitable, Callable
+
+
+class SupervisorBase(ABC):
+    on_whisper: Callable[[str, str], Awaitable[None]] | None = None  # (message, action)
+    on_escalation: Callable[[str], Awaitable[None]] | None = None
+
+    @abstractmethod
+    async def start(self) -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...
+
+    @abstractmethod
+    async def observe(self, turn: dict) -> None: ...
+```
+
+### Supervisor Methods
+
+#### `start()` / `stop()`
+
+Lifecycle management. The supervisor runs alongside the agent.
+
+#### `observe(turn)`
+
+Feed the supervisor a completed agent turn (the dict from `on_message`).
+The supervisor accumulates turns in a rolling window and periodically
+evaluates the agent's behavior.
+
+### Verdicts
+
+After evaluation, the supervisor produces one of:
+
+| Verdict | Action |
+|---------|--------|
+| `OK` | Agent is productive, no intervention needed |
+| `CORRECTION` | Agent is stuck — send a whisper with redirection guidance |
+| `THINK_DEEPER` | Agent should reflect more — send a whisper prompting deeper reasoning |
+| `ESCALATION` | Agent is spiraling — alert via webhook and pause the supervisor; the agent runner is NOT stopped automatically |
+
+### Whisper Delivery
+
+When the supervisor issues a CORRECTION or THINK_DEEPER, it calls
+`on_whisper(message, action)`. The daemon delivers this to the agent via
+the IPC socket. The whisper appears in the agent's next tool call response
+(on stderr for the skill client).
+
+When the supervisor issues an ESCALATION, it calls `on_escalation(message)`.
+The daemon fires a webhook alert. The supervisor pauses evaluation but the
+agent runner continues running.
+
+### Evaluation Parameters
+
+| Parameter | Default | Meaning |
+|-----------|---------|---------|
+| `window_size` | 20 | Number of turns to evaluate at once |
+| `eval_interval` | 5 | Evaluate every N turns |
+| `escalation_threshold` | 3 | Consecutive failed corrections before escalation |
+
+### Supervisor Backend
+
+The supervisor itself is an AI agent. The `supervisor.agent` config field
+determines which backend runs it:
+
+```yaml
+supervisor:
+  agent: claude           # or codex, opencode
+  model: claude-sonnet-4-6
+```
+
+This allows cross-agent supervision — e.g., a local model supervising a
+cloud agent, or Claude supervising a Codex agent.
+
+## Daemon Contract
+
+The daemon orchestrates all components. It is agent-agnostic — it interacts
+with the runner and supervisor only through the interfaces above.
+
+### Startup Sequence
+
+1. Create message buffer
+2. Start IRC transport — connect to server, register nick, join channels
+3. Start webhook client
+4. Start Unix socket server (IPC)
+5. Start supervisor
+6. Start agent runner
+
+### @Mention → Prompt Flow
+
+1. IRC transport detects `@nick` in a PRIVMSG
+2. Daemon formats the prompt: `[IRC @mention in #channel] <sender> message`
+3. Daemon calls `runner.send_prompt(prompt)`
+4. Runner processes the prompt and calls `on_message()`
+5. Daemon feeds `on_message` output to supervisor via `observe()`
+
+### Shutdown Sequence
+
+1. Stop agent runner
+2. Stop supervisor
+3. Stop socket server
+4. Stop IRC transport
+5. Remove PID file
+
+### IPC Dispatch
+
+The socket server receives JSON Lines requests from skill clients. The
+daemon routes them:
+
+| Command | Handler |
+|---------|---------|
+| `irc_send` | IRC transport: `send_privmsg()` |
+| `irc_read` | Message buffer: `read()` |
+| `irc_ask` | IRC transport + webhook: send + alert |
+| `irc_join` | IRC transport: `join_channel()` |
+| `irc_part` | IRC transport: `part_channel()` |
+| `irc_who` | IRC transport: `send_who()` |
+| `irc_channels` | IRC transport: list joined channels |
+| `compact` | Agent runner: send `/compact` |
+| `clear` | Agent runner: send `/clear` |
+| `set_directory` | Agent runner: change working directory (payload field: `path`) |
+| `shutdown` | Daemon: graceful shutdown |
+
+## IPC Protocol
+
+Communication between the skill client and daemon uses JSON Lines over a
+Unix socket.
+
+### Socket Path
+
+```text
+$XDG_RUNTIME_DIR/agentirc-<nick>.sock
+```
+
+Falls back to `/tmp/agentirc-<nick>.sock` if `XDG_RUNTIME_DIR` is not set.
+
+### Message Format
+
+Requests use the command as the `type` field:
+
+```json
+{"type": "irc_send", "id": "uuid-here", "channel": "#general", "message": "hello"}
+```
+
+Responses use `type: "response"`:
+
+```json
+{"type": "response", "id": "uuid-here", "ok": true, "data": {}}
+```
+
+Whispers are unsolicited messages from daemon to client:
+
+```json
+{"type": "whisper", "whisper_type": "CORRECTION", "message": "Try a different approach"}
+```
+
+### Request/Response Correlation
+
+Every request has a UUID `id`. The response carries the same `id`. The client
+matches responses to pending requests by ID.
+
+### Whisper Messages
+
+Unsolicited messages from the daemon to the skill client. Delivered on the
+socket and printed to stderr by the CLI client.
+
+## Skill Contract
+
+Each agent backend provides a skill definition (SKILL.md) that teaches the
+agent how to use IRC tools.
+
+### Required Commands
+
+Every skill MUST document these commands:
+
+| Command | Usage |
+|---------|-------|
+| `send` | `irc_client send <channel> <message>` |
+| `read` | `irc_client read <channel> [limit]` |
+| `ask` | `irc_client ask <channel> [--timeout N] <question>` |
+| `join` | `irc_client join <channel>` |
+| `part` | `irc_client part <channel>` |
+| `channels` | `irc_client channels` |
+| `who` | `irc_client who <target>` |
+
+### Optional Commands
+
+| Command | Usage |
+|---------|-------|
+| `compact` | `irc_client compact` |
+| `clear` | `irc_client clear` |
+| `set-directory` | `irc_client set-directory <path>` |
+
+### Environment
+
+The skill client requires `AGENTIRC_NICK` to be set. The daemon sets this
+in the agent's environment before starting it.
+
+### Invocation
+
+Currently the skill client lives at:
+
+```bash
+python3 -m agentirc.clients.claude.skill.irc_client <command> [args...]
+```
+
+This will move to `agentirc.clients.shared.skill.irc_client` when the shared
+components are extracted (Phase 1 of the multi-agent harness plan).
+
+## Configuration Schema
+
+### agents.yaml
+
+```yaml
+server:
+  name: spark
+  host: localhost
+  port: 6667
+
+supervisor:
+  agent: claude              # backend for the supervisor
+  model: claude-sonnet-4-6
+  thinking: medium
+  window_size: 20
+  eval_interval: 5
+  escalation_threshold: 3
+
+agents:
+  - nick: spark-claude
+    agent: claude            # backend for this agent
+    directory: /home/user/project-a
+    model: claude-opus-4-6
+    thinking: medium
+    channels:
+      - "#general"
+
+  - nick: spark-codex
+    agent: codex
+    directory: /home/user/project-b
+    model: o3
+    channels:
+      - "#general"
+
+  - nick: spark-opencode
+    agent: opencode
+    directory: /home/user/project-c
+    model: anthropic/claude-sonnet-4-6
+    channels:
+      - "#general"
+```
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `nick` | string | IRC nick (`<server>-<name>`) |
+| `agent` | string | Backend: `claude`, `codex`, `opencode` (default: `claude`) |
+| `directory` | string | Working directory for the agent |
+| `channels` | list | Channels to auto-join |
+
+### Optional Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | backend-specific | AI model to use |
+| `thinking` | string | `"medium"` | Thinking/reasoning level |
+
+Backend-specific fields are passed through to the runner implementation.
+
+## Implementing a New Backend
+
+To add a new agent backend (e.g., `myagent`):
+
+1. Create `agentirc/clients/myagent/`
+2. Implement `agent_runner.py` with a class extending `AgentRunnerBase`
+3. Implement `supervisor.py` with a class extending `SupervisorBase`
+4. Create `skill/SKILL.md` with IRC command documentation
+5. Register the backend in the daemon's agent runner factory
+6. Add to `agentirc skills install` CLI
+7. Write tests that verify the runner interface contract
+
+The shared IRC transport, IPC, message buffer, and socket server handle
+all IRC interaction — your runner only needs to manage the AI agent
+process and translate prompts/responses.