taskswarm-cli 0.1.0__py3-none-any.whl

taskswarm/notifications/os_notify.py

@@ -0,0 +1,61 @@
+"""Fires a local OS notification. macOS uses `osascript -e 'display
+notification'` (no extra dependency, ships with the OS). Any other platform
+falls back to a console message plus a terminal bell -- always self-hosted,
+always on by default, no third-party relay involved. Ported from
+src/notify/os-notify.ts."""
+from __future__ import annotations
+
+import platform
+import re
+import subprocess
+import sys
+
+_BEL = chr(7)
+
+# Strips ANSI/terminal control sequences (ESC-prefixed CSI/OSC sequences and
+# raw control characters other than tab/newline) before writing
+# event-derived text to a real terminal. Event fields (session_id, repo,
+# blocked_reason) can originate from an authenticated but otherwise
+# untrusted /events caller, so this fallback -- unlike the escaped
+# AppleScript path -- must not pass them through raw.
+_CONTROL_SEQUENCE_PATTERN = re.compile(
+    r"\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*(\x07|\x1b\\)|[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]"
+)
+
+
+def _sanitize_for_terminal(value: str) -> str:
+    return _CONTROL_SEQUENCE_PATTERN.sub("", value)
+
+
+def send_os_notification(title: str, message: str) -> None:
+    if platform.system() == "Darwin":
+        script = (
+            f"display notification {_quote_applescript_string(message)} "
+            f"with title {_quote_applescript_string(title)}"
+        )
+        try:
+            subprocess.run(
+                ["osascript", "-e", script],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+            )
+        except OSError:
+            # osascript missing/unavailable (e.g. sandboxed CI) -- fall back
+            # so a notification failure never crashes the server process.
+            _fallback_notification(title, message)
+        return
+    _fallback_notification(title, message)
+
+
+def _fallback_notification(title: str, message: str) -> None:
+    # BEL is the terminal bell character -- audible/visible cue in most
+    # terminal emulators even without a graphical OS notification.
+    sys.stdout.write(_BEL)
+    print(f"[taskswarm] {_sanitize_for_terminal(title)}: {_sanitize_for_terminal(message)}")
+
+
+def _quote_applescript_string(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'

taskswarm/schema/__init__.py

@@ -0,0 +1,23 @@
+from .events import (
+    AGENT_STATUSES,
+    AGENT_TYPES,
+    CURRENT_SCHEMA_VERSION,
+    NOTIFY_ON_STATUSES,
+    AgentEvent,
+    EventValidationError,
+    parse_agent_event,
+    parse_agent_event_input,
+    to_agent_event,
+)
+
+__all__ = [
+    "AGENT_STATUSES",
+    "AGENT_TYPES",
+    "CURRENT_SCHEMA_VERSION",
+    "NOTIFY_ON_STATUSES",
+    "AgentEvent",
+    "EventValidationError",
+    "parse_agent_event",
+    "parse_agent_event_input",
+    "to_agent_event",
+]

taskswarm/schema/events.py

@@ -0,0 +1,221 @@
+"""
+The event envelope every part of TaskSwarm agrees on.
+
+Ported from src/schema/events.ts, which uses `zod` for runtime validation.
+This port has zero runtime dependencies, so validation is hand-written here
+instead of pulled in from a schema library -- the field set, limits, and
+error shape are kept equivalent to the TypeScript version's
+`agentEventSchema` / `agentEventInputSchema`.
+"""
+from __future__ import annotations
+
+import re
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+# The current envelope version. Bump this whenever the shape of AgentEvent
+# changes in a way that is not purely additive-and-optional. Consumers can
+# branch on `schema_version` to stay forward compatible.
+CURRENT_SCHEMA_VERSION = 1
+
+# Agent integrations TaskSwarm ships an adapter for in v0.1.
+AGENT_TYPES = ("claude-code", "codex", "cursor", "generic")
+
+# Lifecycle states a tracked session can be in. TaskSwarm's notification
+# layer fires on a transition into 'blocked' | 'needs-review' | 'failed' |
+# 'done' -- the four states that mean "a human should look at this now."
+AGENT_STATUSES = ("queued", "running", "blocked", "needs-review", "done", "failed")
+
+# The subset of statuses that should trigger a notification on transition.
+NOTIFY_ON_STATUSES = frozenset({"blocked", "needs-review", "failed", "done"})
+
+_SESSION_ID_MAX = 256
+_REPO_MAX = 1024
+_BLOCKED_REASON_MAX = 4096
+
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+)
+
+
+class EventValidationError(ValueError):
+    """Raised when a raw dict does not satisfy the AgentEvent(Input) contract.
+
+    `details` mirrors zod's `.flatten()` shape closely enough to be useful
+    for a caller building a `400` response body: a dict of field name to a
+    list of human-readable problem messages.
+    """
+
+    def __init__(self, message: str, details: Optional[Dict[str, List[str]]] = None) -> None:
+        super().__init__(message)
+        self.details: Dict[str, List[str]] = details or {}
+
+
+@dataclass
+class AgentEvent:
+    event_id: str
+    session_id: str
+    repo: str
+    agent_type: str
+    status: str
+    timestamp: str
+    schema_version: int
+    blocked_reason: Optional[str] = field(default=None)
+
+    def to_dict(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {
+            "event_id": self.event_id,
+            "session_id": self.session_id,
+            "repo": self.repo,
+            "agent_type": self.agent_type,
+            "status": self.status,
+            "timestamp": self.timestamp,
+            "schema_version": self.schema_version,
+        }
+        if self.blocked_reason is not None:
+            data["blocked_reason"] = self.blocked_reason
+        return data
+
+
+def _is_uuid(value: Any) -> bool:
+    return isinstance(value, str) and bool(_UUID_RE.match(value))
+
+
+def _is_offset_datetime(value: Any) -> bool:
+    """True for an ISO-8601 datetime string carrying an explicit UTC offset
+    (including a bare "Z"), matching zod's `z.string().datetime({offset:
+    true})`."""
+    if not isinstance(value, str) or len(value) == 0:
+        return False
+    normalized = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        parsed = datetime.fromisoformat(normalized)
+    except ValueError:
+        return False
+    return parsed.tzinfo is not None
+
+
+def _add_error(errors: Dict[str, List[str]], field_name: str, message: str) -> None:
+    errors.setdefault(field_name, []).append(message)
+
+
+def _validate_common(data: Dict[str, Any], errors: Dict[str, List[str]]) -> None:
+    session_id = data.get("session_id")
+    if not isinstance(session_id, str) or not (1 <= len(session_id) <= _SESSION_ID_MAX):
+        _add_error(errors, "session_id", f"must be a string of 1-{_SESSION_ID_MAX} characters")
+
+    repo = data.get("repo")
+    if not isinstance(repo, str) or not (1 <= len(repo) <= _REPO_MAX):
+        _add_error(errors, "repo", f"must be a string of 1-{_REPO_MAX} characters")
+
+    agent_type = data.get("agent_type")
+    if agent_type not in AGENT_TYPES:
+        _add_error(errors, "agent_type", f"must be one of: {', '.join(AGENT_TYPES)}")
+
+    status = data.get("status")
+    if status not in AGENT_STATUSES:
+        _add_error(errors, "status", f"must be one of: {', '.join(AGENT_STATUSES)}")
+
+    blocked_reason = data.get("blocked_reason")
+    if blocked_reason is not None and (
+        not isinstance(blocked_reason, str) or len(blocked_reason) > _BLOCKED_REASON_MAX
+    ):
+        _add_error(errors, "blocked_reason", f"must be a string of at most {_BLOCKED_REASON_MAX} characters")
+
+
+def parse_agent_event_input(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Validates the input shape accepted from the CLI/adapters/HTTP layer:
+    event_id, timestamp, and schema_version are all optional (filled in by
+    `to_agent_event`); everything else is required. Raises
+    EventValidationError with field-level details on failure."""
+    if not isinstance(data, dict):
+        raise EventValidationError("event input must be a JSON object", {"_root": ["must be an object"]})
+
+    errors: Dict[str, List[str]] = {}
+    _validate_common(data, errors)
+
+    event_id = data.get("event_id")
+    if event_id is not None and not _is_uuid(event_id):
+        _add_error(errors, "event_id", "must be a valid UUID")
+
+    timestamp = data.get("timestamp")
+    if timestamp is not None and not _is_offset_datetime(timestamp):
+        _add_error(errors, "timestamp", "must be an ISO-8601 datetime with a UTC offset")
+
+    schema_version = data.get("schema_version")
+    if schema_version is not None and not (isinstance(schema_version, int) and schema_version > 0):
+        _add_error(errors, "schema_version", "must be a positive integer")
+
+    if errors:
+        raise EventValidationError("invalid event", errors)
+
+    result: Dict[str, Any] = {
+        "session_id": data["session_id"],
+        "repo": data["repo"],
+        "agent_type": data["agent_type"],
+        "status": data["status"],
+    }
+    if data.get("blocked_reason") is not None:
+        result["blocked_reason"] = data["blocked_reason"]
+    if event_id is not None:
+        result["event_id"] = event_id
+    if timestamp is not None:
+        result["timestamp"] = timestamp
+    if schema_version is not None:
+        result["schema_version"] = schema_version
+    return result
+
+
+def parse_agent_event(data: Dict[str, Any]) -> AgentEvent:
+    """Validates a fully-stamped event (all fields required) -- used when
+    replaying persisted JSONL log lines, where every event must already
+    carry event_id/timestamp/schema_version."""
+    if not isinstance(data, dict):
+        raise EventValidationError("event must be a JSON object")
+
+    errors: Dict[str, List[str]] = {}
+    _validate_common(data, errors)
+
+    if not _is_uuid(data.get("event_id")):
+        _add_error(errors, "event_id", "must be a valid UUID")
+    if not _is_offset_datetime(data.get("timestamp")):
+        _add_error(errors, "timestamp", "must be an ISO-8601 datetime with a UTC offset")
+    schema_version = data.get("schema_version")
+    if not (isinstance(schema_version, int) and schema_version > 0):
+        _add_error(errors, "schema_version", "must be a positive integer")
+
+    if errors:
+        raise EventValidationError("invalid event", errors)
+
+    return AgentEvent(
+        event_id=data["event_id"],
+        session_id=data["session_id"],
+        repo=data["repo"],
+        agent_type=data["agent_type"],
+        status=data["status"],
+        timestamp=data["timestamp"],
+        schema_version=data["schema_version"],
+        blocked_reason=data.get("blocked_reason"),
+    )
+
+
+def to_agent_event(input_data: Dict[str, Any]) -> AgentEvent:
+    """Fills in event_id/timestamp/schema_version defaults for a partial,
+    already-validated input (the output of parse_agent_event_input)."""
+    event_id = input_data.get("event_id") or str(uuid.uuid4())
+    timestamp = input_data.get("timestamp") or datetime.now(timezone.utc).isoformat().replace(
+        "+00:00", "Z"
+    )
+    schema_version = input_data.get("schema_version") or CURRENT_SCHEMA_VERSION
+    return AgentEvent(
+        event_id=event_id,
+        session_id=input_data["session_id"],
+        repo=input_data["repo"],
+        agent_type=input_data["agent_type"],
+        status=input_data["status"],
+        timestamp=timestamp,
+        schema_version=schema_version,
+        blocked_reason=input_data.get("blocked_reason"),
+    )

taskswarm/server/__init__.py

@@ -0,0 +1,33 @@
+from .config import (
+    DEFAULT_HOST,
+    DEFAULT_PORT,
+    TaskSwarmConfig,
+    generate_token,
+    get_config_path,
+    get_event_log_path,
+    get_taskswarm_home,
+    load_or_create_config,
+    rotate_token,
+    save_config,
+    try_create_config_exclusive,
+)
+from .event_store import EventStore, SessionState
+from .server import RunningServer, start_server
+
+__all__ = [
+    "DEFAULT_HOST",
+    "DEFAULT_PORT",
+    "TaskSwarmConfig",
+    "generate_token",
+    "get_config_path",
+    "get_event_log_path",
+    "get_taskswarm_home",
+    "load_or_create_config",
+    "rotate_token",
+    "save_config",
+    "try_create_config_exclusive",
+    "EventStore",
+    "SessionState",
+    "RunningServer",
+    "start_server",
+]

taskswarm/server/auth.py

@@ -0,0 +1,25 @@
+"""Bearer-token comparison and extraction. Ported from src/server/auth.ts."""
+from __future__ import annotations
+
+import hmac
+import re
+from typing import Optional
+
+_BEARER_RE = re.compile(r"^Bearer\s+(.+)$", re.IGNORECASE)
+
+
+def tokens_match(provided: str, expected: str) -> bool:
+    """Constant-time comparison of two bearer tokens (avoids timing
+    side-channels). `hmac.compare_digest` is the stdlib's constant-time
+    comparator -- the direct Python equivalent of Node's
+    `crypto.timingSafeEqual`, and (like the TS version) it tolerates
+    differing lengths without leaking length via early-exit timing."""
+    return hmac.compare_digest(provided.encode("utf-8"), expected.encode("utf-8"))
+
+
+def extract_bearer_token(authorization_header: Optional[str]) -> Optional[str]:
+    """Extracts a bearer token from an Authorization header value, if present."""
+    if not authorization_header:
+        return None
+    match = _BEARER_RE.match(authorization_header)
+    return match.group(1) if match else None

taskswarm/server/config.py

@@ -0,0 +1,154 @@
+"""Local config: bearer token, host/port, and the opt-in ntfy.sh channel.
+Ported from src/server/config.ts."""
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import stat
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..util.sync_sleep import sleep_sync_ms
+
+DEFAULT_PORT = 4173
+DEFAULT_HOST = "127.0.0.1"
+
+
+@dataclass
+class TaskSwarmConfig:
+    token: str
+    port: int = DEFAULT_PORT
+    host: str = DEFAULT_HOST
+    ntfy: Dict[str, Any] = field(default_factory=lambda: {"enabled": False})
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"token": self.token, "port": self.port, "host": self.host, "ntfy": self.ntfy}
+
+
+def get_taskswarm_home() -> str:
+    """Root directory for all TaskSwarm local state. Overridable for tests
+    via TASKSWARM_HOME."""
+    return os.environ.get("TASKSWARM_HOME") or str(Path.home() / ".taskswarm")
+
+
+def get_config_path() -> str:
+    return str(Path(get_taskswarm_home()) / "config.json")
+
+
+def get_event_log_path() -> str:
+    return str(Path(get_taskswarm_home()) / "events.jsonl")
+
+
+def generate_token() -> str:
+    """Generates a cryptographically random bearer token (256 bits, URL-safe)."""
+    return secrets.token_urlsafe(32)
+
+
+def _ensure_home_dir() -> None:
+    home = Path(get_taskswarm_home())
+    home.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        os.chmod(home, 0o700)
+    except OSError:
+        # best-effort on platforms/filesystems that don't support POSIX perms
+        pass
+
+
+def _default_config() -> TaskSwarmConfig:
+    return TaskSwarmConfig(token=generate_token(), port=DEFAULT_PORT, host=DEFAULT_HOST, ntfy={"enabled": False})
+
+
+def _write_config(config: TaskSwarmConfig) -> None:
+    _ensure_home_dir()
+    path = get_config_path()
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(json.dumps(config.to_dict(), indent=2) + "\n")
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def try_create_config_exclusive(config: TaskSwarmConfig) -> bool:
+    """Attempts to create the config file exclusively (fails if another
+    process already created it). Returns True if this call won the race and
+    wrote the file, False if another process got there first. Exported so
+    the TOCTOU-loss path can be exercised directly and deterministically in
+    tests, without needing to fake real multi-process OS scheduling."""
+    _ensure_home_dir()
+    path = get_config_path()
+    payload = json.dumps(config.to_dict(), indent=2) + "\n"
+    try:
+        fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return False
+    try:
+        os.write(fd, payload.encode("utf-8"))
+    finally:
+        os.close(fd)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+    return True
+
+
+def _read_config_file_with_retry(path: str) -> Dict[str, Any]:
+    """Reads and parses the config file, retrying briefly on a parse
+    failure. Guards the narrow window where we lost the exclusive-create
+    race and the winning process has created the file but not yet finished
+    flushing its contents."""
+    max_attempts = 25
+    retry_delay_ms = 4
+    last_error: Optional[Exception] = None
+    for _ in range(max_attempts):
+        try:
+            with open(path, "r", encoding="utf-8") as handle:
+                return json.load(handle)
+        except (OSError, json.JSONDecodeError) as error:
+            last_error = error
+            sleep_sync_ms(retry_delay_ms)
+    assert last_error is not None
+    raise last_error
+
+
+def load_or_create_config() -> TaskSwarmConfig:
+    """Loads the config, creating it (with a freshly generated token) on
+    first run. First-boot creation is race-safe: if two processes both see
+    no config file and race to create one, exactly one of them wins the
+    exclusive create and the loser re-reads the winner's file instead of
+    generating and persisting a second, different token."""
+    _ensure_home_dir()
+    path = get_config_path()
+    if not os.path.exists(path):
+        config = _default_config()
+        if try_create_config_exclusive(config):
+            return config
+        # Lost the race: another process already created the file first.
+        # Fall through and read what it wrote rather than clobbering it.
+
+    parsed = _read_config_file_with_retry(path)
+    ntfy = parsed.get("ntfy") or {}
+    merged = TaskSwarmConfig(
+        token=parsed.get("token") or generate_token(),
+        port=parsed.get("port") or DEFAULT_PORT,
+        host=parsed.get("host") or DEFAULT_HOST,
+        ntfy={"enabled": bool(ntfy.get("enabled", False)), **({"topicUrl": ntfy["topicUrl"]} if ntfy.get("topicUrl") else {})},
+    )
+    if not parsed.get("token"):
+        _write_config(merged)
+    return merged
+
+
+def save_config(config: TaskSwarmConfig) -> None:
+    _write_config(config)
+
+
+def rotate_token() -> str:
+    """Regenerates the bearer token and persists it. Returns the new token."""
+    config = load_or_create_config()
+    config.token = generate_token()
+    _write_config(config)
+    return config.token

taskswarm/server/event_store.py

@@ -0,0 +1,139 @@
+"""In-memory event store keyed by session_id, backed by an append-only JSONL
+log on disk for durability across restarts. No embedded database: this is a
+deliberate choice to keep the tool lightweight, dependency-free, and
+ARM-friendly (no native binary compile step). Ported from
+src/server/event-store.ts.
+
+Thread safety: the HTTP server (server/http_server.py) runs each connection
+on its own thread (`http.server.ThreadingHTTPServer`), so every method here
+that touches `_sessions` or the on-disk log is guarded by a single lock.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from ..schema.events import AgentEvent, parse_agent_event
+
+# Longest raw line content ever echoed back in a corrupt-line warning.
+_CORRUPT_LINE_PREVIEW_LIMIT = 200
+
+
+@dataclass
+class SessionState:
+    session_id: str
+    latest: AgentEvent
+    history: List[AgentEvent] = field(default_factory=list)
+
+
+class EventStore:
+    """Emits to registered listeners whenever a new event lands, so the HTTP
+    layer can fan it out to connected /live clients."""
+
+    def __init__(self, log_path: Optional[str] = None, warn: Optional[Callable[[str], None]] = None) -> None:
+        self._sessions: "dict[str, SessionState]" = {}
+        self._log_path = log_path
+        self._warn = warn or (lambda message: print(message, flush=True))
+        self._listeners: List[Callable[[AgentEvent], None]] = []
+        self._lock = threading.Lock()
+        if self._log_path:
+            self._ensure_log_file(self._log_path)
+            self._replay(self._log_path)
+
+    def _ensure_log_file(self, log_path: str) -> None:
+        directory = os.path.dirname(log_path)
+        if directory and not os.path.exists(directory):
+            os.makedirs(directory, mode=0o700, exist_ok=True)
+        if not os.path.exists(log_path):
+            fd = os.open(log_path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
+            os.close(fd)
+
+    def _replay(self, log_path: str) -> None:
+        """Rebuilds in-memory state by replaying every line of the JSONL
+        log. Corrupt/partial lines (e.g. a torn write from a crash
+        mid-append) are skipped rather than failing startup entirely --
+        durability is best-effort, not a hard guarantee for the last
+        unflushed line -- but each skip is logged so a torn write or
+        bit-rot is visible to the operator instead of silently erasing
+        history."""
+        with open(log_path, "r", encoding="utf-8") as handle:
+            raw = handle.read()
+        for line_number, line in enumerate(raw.split("\n"), start=1):
+            if line.strip() == "":
+                continue
+            try:
+                parsed = parse_agent_event(json.loads(line))
+                self._apply_to_memory(parsed)
+            except Exception:
+                self._warn_corrupt_line(log_path, line_number, line)
+
+    def _warn_corrupt_line(self, log_path: str, line_number: int, line: str) -> None:
+        preview = (
+            f"{line[:_CORRUPT_LINE_PREVIEW_LIMIT]}... (truncated, {len(line)} chars total)"
+            if len(line) > _CORRUPT_LINE_PREVIEW_LIMIT
+            else line
+        )
+        self._warn(f"taskswarm: skipping unparseable event on line {line_number} of {log_path}: {preview}")
+
+    def _apply_to_memory(self, event: AgentEvent) -> None:
+        existing = self._sessions.get(event.session_id)
+        if existing:
+            existing.history.append(event)
+            existing.latest = event
+        else:
+            self._sessions[event.session_id] = SessionState(
+                session_id=event.session_id, latest=event, history=[event]
+            )
+
+    def append(self, event: AgentEvent) -> "tuple[Optional[str], Optional[str]]":
+        """Appends a validated event to the log (if persistence is enabled)
+        and updates in-memory state. Returns (previous_status,
+        previous_blocked_reason) for the session (both None if this is the
+        session's first event) so callers can decide whether a state
+        transition warrants a notification -- notification dedup keys on
+        the (status, blocked_reason) pair together, not status alone, so
+        both are needed."""
+        with self._lock:
+            previous = self._sessions.get(event.session_id)
+            previous_status = previous.latest.status if previous else None
+            previous_blocked_reason = previous.latest.blocked_reason if previous else None
+            if self._log_path:
+                with open(self._log_path, "a", encoding="utf-8") as handle:
+                    handle.write(json.dumps(event.to_dict()) + "\n")
+                try:
+                    os.chmod(self._log_path, 0o600)
+                except OSError:
+                    pass
+            self._apply_to_memory(event)
+            listeners = list(self._listeners)
+        for listener in listeners:
+            listener(event)
+        return previous_status, previous_blocked_reason
+
+    def get_session(self, session_id: str) -> Optional[SessionState]:
+        with self._lock:
+            return self._sessions.get(session_id)
+
+    def list_sessions(self) -> List[SessionState]:
+        """All tracked sessions' latest state, sorted most-recently-updated first."""
+        with self._lock:
+            sessions = list(self._sessions.values())
+        return sorted(sessions, key=lambda s: s.latest.timestamp, reverse=True)
+
+    def size(self) -> int:
+        with self._lock:
+            return len(self._sessions)
+
+    def add_listener(self, listener: Callable[[AgentEvent], None]) -> None:
+        with self._lock:
+            self._listeners.append(listener)
+
+    def remove_listener(self, listener: Callable[[AgentEvent], None]) -> None:
+        with self._lock:
+            if listener in self._listeners:
+                self._listeners.remove(listener)