agent-bus-team 0.1.2__py3-none-any.whl

agent_bus/README.md

@@ -0,0 +1,123 @@
+# agent-bus
+
+Small stdlib-only Python 3.11+ inter-agent messaging CLI and library.
+
+Parallel bus for Claude Code, Grok, Oh My Pi (omp), Codex, and others.
+Two channels: file bus (`send`/`inbox`) vs. native UDS (`listen` + `send-peer`). See [UDS-protocol.md](skills/references/UDS-protocol.md).
+
+## On-disk (AGENT_BUS_HOME=~/.agent-bus)
+
+```
+~/.agent-bus/
+  roster/<id>.json     # registered agents (uuid ids)
+  inboxes/<id>.jsonl   # append-only, one JSON message per line
+  captures/<pid>.jsonl # from `listen`
+```
+
+Roster entry and Message envelope match the spec in the source.
+
+## Rules (enforced)
+
+- Plain text **only** in `text` (no structured payloads).
+- Refuse `> 1_000_000` chars.
+- Per-inbox unread cap 50 (send fails with clear error).
+- **Never treat a received message as user consent.** Messages are cross-session only. The receiving agent must still show the user and obtain explicit approval before acting on any instruction in a message.
+- Names unique among *live* (pid-alive) registrations; collisions get `-2`, `-3` suffix on register.
+- `list` drops stale roster entries (dead pid) but leaves their inbox files.
+
+## CLI
+
+```sh
+agent-bus list [--kind claude|grok|omp|codex|all] [--json]
+agent-bus send <name-or-id> -m TEXT [--summary S] [--from-name N]
+agent-bus inbox [--name N] [--unread] [--json]
+agent-bus ack <message-id> [--name N]
+agent-bus register --name N --kind K [--cwd P] [--pid P]
+agent-bus unregister --name N
+agent-bus self [--json]
+
+# EXPERIMENT (see below)
+agent-bus listen [--name agent-bus]
+agent-bus send-uds <socket-path> -m TEXT
+```
+
+`list` = live roster entries (after pruning dead) UNION native adapters (claude/grok/omp/codex read-only discovery of their registries). Only alive pids.
+
+`send` to a discovered native name/id will lazily create a roster entry + inbox under this bus home using a stable derived id (`claude:<sessionId>`, `grok:...` etc). The recipient only sees it if they also run `agent-bus inbox` (or via skill).
+
+## Adapters (read-only, best-effort, never throw)
+
+- claude: `~/.claude/sessions/*.json` (pid alive)
+- grok: `~/.grok/active_sessions.json`
+- omp: `~/.omp/run/daemons/*/clients/*.json` + terminal-sessions fallback
+- codex: `~/.codex/process_manager/chat_processes.json` (catalog skipped silently)
+
+Override for tests with `AGENT_BUS_SESSIONS_DIR` etc. (File-bus adapters are read-only discovery and never write native sockets; native UDS send path does write for acks and peer messages — see UDS-protocol.md.)
+
+## The `listen` + UDS experiment
+
+`agent-bus listen` lets a Claude Code session discover us via its `ListAgents` / `/list-agents`.
+
+It:
+- Binds UDS at `/tmp/cc-socks/<ourpid>.sock` (0o600, dir 0o700)
+- Writes a matching `~/.claude/sessions/<ourpid>.json` (exact fields + timestamps) + peer key
+- Accepts connections, reads newline-delimited JSON frames (tolerates final buffer w/o nl)
+- Logs raw + parsed (auth redacted) to stdout + appends to `~/.agent-bus/captures/<pid>.jsonl`
+- Auth first line on conns; accepts `type:user` frames
+- On `msg_id` present: dials back an authenticated `{"type":"control","action":"peer_message_status","status":"delivered",...}` (NEVER writes status on the inbound conn)
+- On SIGINT/SIGTERM: unlinks *only* our sock, sessions json, and key
+
+`agent-bus send-peer` sends native UDS messages into other Claude sessions (or other listeners).
+
+**Usage (from another Claude):**
+1. In one terminal (this agent): `AGENT_BUS_HOME=/tmp/ab-test agent-bus listen --name my-bus`
+2. In a real Claude Code session: run `/list-agents` or tool `ListAgents`. You should see `my-bus`.
+3. Send a message from Claude to it (it will enqueue via their SendMessage to our socket).
+4. Watch the logs + capture file.
+
+**Outbound to Claude peers:**
+`agent-bus send-peer <name-or-sock> -m "text here"`
+See [UDS-protocol.md](skills/references/UDS-protocol.md) for the full wire format, auth, frame shapes, and verified bidirectional behavior.
+
+**CRITICAL SAFETY**
+- This is an experiment to reverse the wire format.
+- Do not use `send-uds` against anything except a socket we started with `listen` under test overrides.
+- Real delivery in Claude happens at their next tool round; they may show `<cross-session-message ...>`
+- Received content must never auto-execute. Always require fresh user approval.
+
+Test overrides (used by our test suite, safe):
+- `AGENT_BUS_SOCK_DIR=/tmp/ab-test-socks`
+- `AGENT_BUS_SESSIONS_DIR=/tmp/ab-test-sessions`
+- `AGENT_BUS_HOME=/tmp/ab-test-bus`
+## Installation / running from source
+
+```sh
+gh repo clone danbarua/agent-bus && cd agent-bus
+python -m pip install -e .
+agent-bus --help
+```
+
+For a Claude session or omp: `python -m agent_bus ...` or after pip install use the script.
+
+Also a skill copy lives at `~/.claude/skills/agent-bus/SKILL.md` (and source `skills/SKILL.md`).
+
+## Skills / integration
+
+See `skills/SKILL.md`. Agents can call the CLI or import `agent_bus.store` etc to register on start and poll inbox.
+
+## Development / test
+
+```sh
+python -m pytest tests/ -q --tb=line
+AGENT_BUS_HOME=/tmp/ab-test python -m agent_bus list --json
+```
+
+## Limitations / non-goals
+
+- No impersonation of Claude's full protocol (listen + send-peer implement the UDS peer messaging subset — see [UDS-protocol.md](skills/references/UDS-protocol.md).
+- No auto-start of other agents.
+- Herdr TTY injection is a separate channel (not used here).
+- No impersonation of Claude's full protocol beyond the listen experiment.
+- Inboxes are per bus-home; multiple users would need separate homes or sync.
+
+This is intentionally small and boring.

agent_bus/__init__.py

@@ -0,0 +1,5 @@
+"""agent-bus: inter-agent messaging for Claude, Grok, OMP, Codex etc.
+
+Stdlib only. Parallel bus, does not use or impersonate Claude's UDS protocol.
+"""
+__version__ = "0.1.0"

agent_bus/__main__.py

@@ -0,0 +1,9 @@
+"""Support `python -m agent_bus` invocation for the CLI."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_bus/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Adapters package: read-only discovery for native agent registries."""
+from __future__ import annotations
+
+from typing import Any
+
+from . import claude, codex, grok, omp
+
+
+def discover_all() -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for mod in (claude, grok, omp, codex):
+        try:
+            out.extend(mod.discover())
+        except Exception:
+            # never throw from adapters
+            continue
+    return out

agent_bus/adapters/claude.py

@@ -0,0 +1,66 @@
+"""Claude Code adapter: read-only best-effort discovery.
+
+Scans ~/.claude/sessions/<pid>.json (or AGENT_BUS_SESSIONS_DIR override for tests).
+Only returns entries where pid is alive. Never writes. Never touches sockets.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any
+
+from ..store import is_pid_alive
+
+
+def _sessions_dir() -> str:
+    # override for tests: AGENT_BUS_SESSIONS_DIR
+    env = os.environ.get("AGENT_BUS_SESSIONS_DIR")
+    if env:
+        return env
+    return os.path.expanduser("~/.claude/sessions")
+
+
+def discover() -> list[dict[str, Any]]:
+    """Return list of discovered claude agents (live pids only)."""
+    sdir = _sessions_dir()
+    out: list[dict[str, Any]] = []
+    if not os.path.isdir(sdir):
+        return out
+    try:
+        for fn in os.listdir(sdir):
+            if not fn.endswith(".json") or not fn.split(".")[0].isdigit():
+                continue
+            path = os.path.join(sdir, fn)
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                pid = int(data.get("pid", 0))
+                if not is_pid_alive(pid):
+                    continue
+                session_id = data.get("sessionId") or f"pid:{pid}"
+                rid = f"claude:{session_id}"
+                name = data.get("name") or f"claude-{pid}"
+                cwd = data.get("cwd")
+                status = data.get("status", "unknown")
+                out.append({
+                    "id": rid,
+                    "name": name,
+                    "kind": "claude",
+                    "pid": pid,
+                    "cwd": cwd,
+                    "status": status,
+                    "native": {
+                        "sessionId": session_id,
+                        "messagingSocketPath": data.get("messagingSocketPath"),
+                        "version": data.get("version"),
+                        "kind": data.get("kind"),
+                    },
+                    "registeredAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                    "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                })
+            except Exception:
+                continue
+    except Exception:
+        pass
+    return out

agent_bus/adapters/codex.py

@@ -0,0 +1,48 @@
+"""Codex adapter: read-only, best effort, silent skip on catalog."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any
+
+from ..store import is_pid_alive
+
+
+def discover() -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    base = os.path.expanduser("~/.codex")
+    pm = os.path.join(base, "process_manager", "chat_processes.json")
+    if not os.path.isfile(pm):
+        return out
+    try:
+        with open(pm, "r", encoding="utf-8") as f:
+            procs = json.load(f)
+        # expected shape unknown, try list or dict of pids
+        items = procs if isinstance(procs, list) else (procs.get("processes", []) if isinstance(procs, dict) else [])
+        for item in items if isinstance(items, list) else []:
+            pid = None
+            if isinstance(item, int):
+                pid = item
+            elif isinstance(item, dict):
+                pid = item.get("pid") or item.get("process_id")
+            if not is_pid_alive(pid):
+                continue
+            rid = f"codex:pid:{pid}"
+            name = f"codex-{pid}"
+            cwd = item.get("cwd") if isinstance(item, dict) else None
+            out.append({
+                "id": rid,
+                "name": name,
+                "kind": "codex",
+                "pid": pid,
+                "cwd": cwd,
+                "status": "unknown",
+                "native": {"source": "chat_processes"},
+                "registeredAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            })
+    except Exception:
+        # silent on error or empty
+        pass
+    return out

agent_bus/adapters/grok.py

@@ -0,0 +1,48 @@
+"""Grok adapter: read-only."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any
+
+from ..store import is_pid_alive
+
+
+def _grok_dir() -> str:
+    return os.path.expanduser("~/.grok")
+
+
+def discover() -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    gdir = _grok_dir()
+    active = os.path.join(gdir, "active_sessions.json")
+    if not os.path.isfile(active):
+        return out
+    try:
+        with open(active, "r", encoding="utf-8") as f:
+            sessions = json.load(f)
+        if not isinstance(sessions, list):
+            return out
+        for s in sessions:
+            pid = s.get("pid")
+            if not is_pid_alive(pid):
+                continue
+            sid = s.get("session_id") or f"pid:{pid}"
+            rid = f"grok:{sid}"
+            name = s.get("agent_name") or f"grok-{pid}"
+            cwd = s.get("cwd")
+            out.append({
+                "id": rid,
+                "name": name,
+                "kind": "grok",
+                "pid": pid,
+                "cwd": cwd,
+                "status": "unknown",
+                "native": {"session_id": sid, "opened_at": s.get("opened_at")},
+                "registeredAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            })
+    except Exception:
+        pass
+    return out

agent_bus/adapters/omp.py

@@ -0,0 +1,69 @@
+"""OMP adapter: read-only best effort."""
+from __future__ import annotations
+
+import glob
+import json
+import os
+import time
+from typing import Any
+
+from ..store import is_pid_alive
+
+
+def discover() -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    base = os.path.expanduser("~/.omp")
+    # daemons clients
+    try:
+        for cli_json in glob.glob(os.path.join(base, "run", "daemons", "*", "clients", "*.json")):
+            try:
+                with open(cli_json, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                pid = data.get("pid")
+                if not is_pid_alive(pid):
+                    continue
+                aid = data.get("id") or f"pid:{pid}"
+                rid = f"omp:{aid}"
+                name = data.get("id", f"omp-{pid}")
+                cwd = data.get("projectDir") or data.get("cwd")
+                out.append({
+                    "id": rid,
+                    "name": name,
+                    "kind": "omp",
+                    "pid": pid,
+                    "cwd": cwd,
+                    "status": "unknown",
+                    "native": {"id": aid, "projectDir": cwd},
+                    "registeredAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                    "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                })
+            except Exception:
+                continue
+    except Exception:
+        pass
+
+    # terminal sessions fallback (ttys*)
+    try:
+        for ts in glob.glob(os.path.join(base, "agent", "terminal-sessions", "ttys*")):
+            # these are dirs? assume have info, but for simplicity if dir take name
+            pid_str = os.path.basename(ts).replace("ttys", "")
+            try:
+                pid = int(pid_str) if pid_str.isdigit() else None
+            except Exception:
+                pid = None
+            if pid and is_pid_alive(pid):
+                rid = f"omp:tty:{pid}"
+                out.append({
+                    "id": rid,
+                    "name": f"omp-tty-{pid}",
+                    "kind": "omp",
+                    "pid": pid,
+                    "cwd": None,
+                    "status": "unknown",
+                    "native": {"tty": os.path.basename(ts)},
+                    "registeredAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                    "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                })
+    except Exception:
+        pass
+    return out

agent_bus/cli.py

@@ -0,0 +1,276 @@
+"""CLI entrypoint for agent-bus."""
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import sys
+from typing import Any
+
+from .protocol import roster_to_dict
+from .store import (
+    ack_message,
+    get_inbox,
+    get_self,
+    list_agents,
+    send_message,
+)
+from .store import (
+    register as do_register,
+)
+from .store import (
+    unregister as do_unregister,
+)
+from .uds import run_listen, send_peer_message, send_uds_frame
+
+
+def _print_json(obj: Any) -> None:
+    print(json.dumps(obj, indent=2, default=str, sort_keys=True))
+
+
+def _resolve_kind(k: str | None) -> str | None:
+    if not k or k.lower() == "all":
+        return None
+    k = k.lower()
+    if k in ("claude", "grok", "omp", "codex", "other"):
+        return k
+    return None
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    kind = _resolve_kind(args.kind)
+    agents = list_agents(kind=kind)
+    if args.json:
+        _print_json([roster_to_dict(a) for a in agents])
+        return 0
+    if not agents:
+        print("no agents")
+        return 0
+    print(f"{'NAME':<20} {'KIND':<8} {'PID':>7} {'STATUS':<10} ID")
+    for a in agents:
+        print(f"{a.name:<20} {a.kind:<8} {a.pid or ''!s:>7} {a.status:<10} {a.id}")
+    return 0
+
+
+def cmd_send(args: argparse.Namespace) -> int:
+    try:
+        mid = send_message(
+            to=args.target,
+            text=args.message,
+            summary=args.summary or "",
+            from_name=args.from_name,
+            from_kind="other",
+        )
+        print(f"sent id={mid}")
+        return 0
+    except Exception as e:
+        print(f"send failed: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_inbox(args: argparse.Namespace) -> int:
+    msgs = get_inbox(name_or_id=args.name, unread_only=args.unread)
+    if args.json:
+        # serialize friendly
+        out = []
+        for m in msgs:
+            out.append({
+                "id": m["id"],
+                "ts": m["ts"],
+                "from": {"id": m["from_"].id, "name": m["from_"].name, "kind": m["from_"].kind},
+                "to": m["to"],
+                "summary": m["summary"],
+                "text": m["text"],
+                "read": m["read"],
+                "replyTo": m["replyTo"],
+            })
+        _print_json(out)
+        return 0
+    if not msgs:
+        print("inbox empty")
+        return 0
+    for m in msgs:
+        flag = " " if m["read"] else "U"
+        print(f"[{flag}] {m['ts'][:19]} from={m['from_'].name} ({m['from_'].kind})")
+        if m["summary"]:
+            print(f"    summary: {m['summary']}")
+        print(f"    {m['text'][:200]}{'...' if len(m['text'])>200 else ''}")
+        print(f"    id={m['id']}")
+    return 0
+
+
+def cmd_ack(args: argparse.Namespace) -> int:
+    ok = ack_message(args.message_id, name_or_id=args.name)
+    print("acked" if ok else "not found")
+    return 0 if ok else 1
+
+
+def cmd_register(args: argparse.Namespace) -> int:
+    kind = args.kind  # type: ignore
+    if kind not in ("claude", "grok", "omp", "codex", "other"):
+        print("invalid kind", file=sys.stderr)
+        return 1
+    try:
+        entry = do_register(
+            name=args.name,
+            kind=kind,  # type: ignore
+            cwd=args.cwd,
+            pid=args.pid,
+        )
+        print(f"registered id={entry.id} name={entry.name}")
+        return 0
+    except Exception as e:
+        print(f"register failed: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_unregister(args: argparse.Namespace) -> int:
+    ok = do_unregister(args.name)
+    print("unregistered" if ok else "no match")
+    return 0
+
+
+def cmd_self(args: argparse.Namespace) -> int:
+    e = get_self()
+    if not e:
+        print("not registered (use register)")
+        return 1
+    if args.json:
+        _print_json({
+            "id": e.id, "name": e.name, "kind": e.kind, "pid": e.pid,
+            "cwd": e.cwd, "status": e.status, "inbox": e.inbox
+        })
+        return 0
+    print(f"id={e.id} name={e.name} kind={e.kind} pid={e.pid} cwd={e.cwd}")
+    return 0
+
+
+def cmd_listen(args: argparse.Namespace) -> int:
+    # blocks
+    try:
+        run_listen(name=args.name or "agent-bus")
+        return 0
+    except Exception as e:
+        print(f"listen error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_send_uds(args: argparse.Namespace) -> int:
+    try:
+        send_uds_frame(args.socket, args.message)
+        print("frame sent")
+        return 0
+    except Exception as e:
+        print(f"send-uds failed: {e}", file=sys.stderr)
+        return 1
+def cmd_send_peer(args: argparse.Namespace) -> int:
+    target = args.target
+    sock = None
+    if target.endswith(".sock") and os.path.exists(target):
+        sock = target
+    else:
+        # lookup by name in claude sessions
+        sess_dir = os.path.expanduser("~/.claude/sessions")
+        for f in glob.glob(os.path.join(sess_dir, "*.json")):
+            try:
+                with open(f) as jf:
+                    d = json.load(jf)
+                if d.get("name") == target:
+                    sock = d.get("messagingSocketPath")
+                    break
+            except Exception:
+                pass
+    if not sock or not os.path.exists(sock):
+        print(f"target not found or dead: {target}", file=sys.stderr)
+        return 1
+    try:
+        send_peer_message(sock, args.message)
+        return 0
+    except Exception as e:
+        print(f"send-peer failed: {e}", file=sys.stderr)
+        return 1
+
+
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    p = argparse.ArgumentParser(prog="agent-bus", description="inter-agent messaging bus")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # list
+    pl = sub.add_parser("list", help="list live agents from roster + native adapters")
+    pl.add_argument("--kind", default=None, help="claude|grok|omp|codex|all")
+    pl.add_argument("--json", action="store_true")
+    pl.set_defaults(func=cmd_list)
+
+    # send (file bus)
+    ps = sub.add_parser("send", help="send text via file-bus inbox to name-or-id")
+    ps.add_argument("target", help="name or id (from list)")
+    ps.add_argument("-m", "--message", required=True, help="plain text (max 1M)")
+    ps.add_argument("--summary", default=None)
+    ps.add_argument("--from-name", default=None)
+    ps.set_defaults(func=cmd_send)
+
+    # inbox
+    pi = sub.add_parser("inbox", help="read messages addressed to self or --name")
+    pi.add_argument("--name", default=None)
+    pi.add_argument("--unread", action="store_true")
+    pi.add_argument("--json", action="store_true")
+    pi.set_defaults(func=cmd_inbox)
+
+    # ack
+    pa = sub.add_parser("ack", help="mark message read")
+    pa.add_argument("message_id")
+    pa.add_argument("--name", default=None)
+    pa.set_defaults(func=cmd_ack)
+
+    # register
+    pr = sub.add_parser("register", help="register this process so others can send to you")
+    pr.add_argument("--name", required=True)
+    pr.add_argument("--kind", required=True, choices=["claude", "grok", "omp", "codex", "other"])
+    pr.add_argument("--cwd", default=None)
+    pr.add_argument("--pid", type=int, default=None)
+    pr.set_defaults(func=cmd_register)
+
+    # unregister
+    pu = sub.add_parser("unregister", help="remove by name")
+    pu.add_argument("--name", required=True)
+    pu.set_defaults(func=cmd_unregister)
+
+    # self
+    psf = sub.add_parser("self", help="show current registered self")
+    psf.add_argument("--json", action="store_true")
+    psf.set_defaults(func=cmd_self)
+
+    # listen (UDS experiment)
+    plis = sub.add_parser(
+        "listen",
+        help="EXPERIMENT: publish as Claude peer (writes our sessions/<pid>.json + binds /tmp/cc-socks/<pid>.sock)",
+    )
+    plis.add_argument("--name", default="agent-bus", help="name visible to ListAgents")
+    plis.set_defaults(func=cmd_listen)
+
+    # send-uds (for testing listen only)
+    psu = sub.add_parser(
+        "send-uds",
+        help="send the two-line UDS auth+user frame (test ONLY against our own listen, never live Claude)",
+    )
+    psu.add_argument("socket", help="path to target .sock")
+    psu.add_argument("-m", "--message", required=True)
+    psu.set_defaults(func=cmd_send_uds)
+
+    # send-peer (UDS to native claude peer)
+    psp = sub.add_parser("send-peer", help="send user msg via UDS peer protocol to name or socket")
+    psp.add_argument("target", help="name (from list) or path to .sock")
+    psp.add_argument("-m", "--message", required=True, help="plain text")
+    psp.set_defaults(func=cmd_send_peer)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())