parley-agents 0.1.0__tar.gz

parley_agents-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+*.db
+.venv/

parley_agents-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: parley-agents
+Version: 0.1.0
+Summary: Broker-agnostic messaging layer that lets AI agents (and humans) on different machines talk in named rooms and wake each other.
+Author: TYO Lab
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: nats
+Requires-Dist: nats-py>=2.6; extra == 'nats'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: tyomq
+Requires-Dist: tyo-mq-client>=0.3.0; extra == 'tyomq'
+Description-Content-Type: text/markdown
+
+# Parley
+
+Parley is broker-agnostic messaging for AI agents, and humans, working across different machines. Agents join named rooms, post and poll for messages, and wake each other up when something new arrives. It runs with zero infrastructure to start: a SQLite file and simple polling, no message broker, no database server to stand up.
+
+## Install
+
+```bash
+pip install parley-agents
+```
+
+The package name is `parley-agents`, but the import and CLI name is `parley`:
+
+```bash
+parley serve
+python -c "import parley"
+```
+
+The optional extras `[postgres]`, `[tyomq]`, `[redis]`, and `[nats]` are declared in `pyproject.toml` for future releases. This MVP ships with only the SQLite store and the polling transport; the other backends are not implemented yet, so installing those extras today pulls in dependencies with no adapter behind them.
+
+## Quickstart (2 minutes)
+
+```bash
+# terminal 1
+parley serve            # gateway on 127.0.0.1:8790, SQLite at ~/.parley/parley.db
+
+# terminal 2 — create a room and post as alice
+python -c "import asyncio, parley; asyncio.run(parley.Client(agent='alice').create_room('general'))"
+PARLEY_AGENT=bob parley join general
+PARLEY_AGENT=bob parley watch general      # live-tails the room
+
+# terminal 3
+PARLEY_AGENT=alice parley say general "hi bob"   # bob's watch prints it
+```
+
+## Python SDK
+
+```python
+import asyncio
+from parley import Client
+
+async def main():
+    alice = Client(agent="alice")
+    bob = Client(agent="bob")
+
+    await alice.create_room("standup", title="Daily")
+    await bob.join("standup")
+
+    await alice.say("standup", "what did you ship?")
+    await bob.say("standup", "the poll cursor")
+
+    # each hears the other's messages, not their own
+    for conv in await alice.poll():
+        for msg in conv["messages"]:
+            print(msg["body"])
+
+    await alice.close()
+    await bob.close()
+
+asyncio.run(main())
+```
+
+## MCP (any agent)
+
+Any MCP-capable agent (not just Python) can join Parley rooms without the SDK, using the bundled MCP server. The gateway serves both the REST API and an MCP endpoint side by side:
+
+1. `parley serve --token <admin-secret>` starts the gateway on `127.0.0.1:8790` and now also serves the MCP app on `port + 1` (8791 by default).
+2. `parley token --gw http://host:8790 --admin-token <admin-secret> --box <box>` mints a per-agent token, scoped to a box, and prints it. This is an admin operation: only the holder of the admin secret can mint tokens.
+3. `parley init --url http://host:8791/mcp --token <agent-token>` writes the Parley MCP server into the agent's config, `~/.claude.json` by default (override with `--file`). It adds an entry under `mcpServers` carrying the bearer token and an `X-Parley-Agent` header templated from an environment variable.
+4. Set `PARLEY_AGENT` per session, e.g. `work3-agent#1`, so each session on a box has a distinct handle. The gateway composes the effective identity from `box + handle`, and the box always comes from the authenticated token, never from a header the client controls.
+
+A token authenticates a box, not a single session. A box token may assume any handle within its own box namespace (`<box>-*`), so treat it as a box-level secret: a leaked box token can impersonate every session on that box. Mint one token per box and keep it on that box.
+
+## How it works
+
+Parley has three parts:
+
+- A gateway (FastAPI) exposing rooms, messages, and polling over HTTP.
+- A pluggable Store, the source of truth for rooms, membership, and message history. SQLite is the zero-config default; a Postgres store is also available for production (see below).
+- A pluggable Transport, used only to carry a nudge signal ("something changed in room X") so a client knows when to poll again. The MVP ships polling (no real transport, just cheap re-checks); push transports such as tyo-mq, Redis, and NATS are planned. The transport never carries message bodies, so swapping it in or out changes nothing about durability or correctness.
+
+Each call to `poll()` advances a per-room read cursor for that agent, so messages are delivered once. Distinct identities always hear each other. A bare box (no explicit agent handle) hears its own same-box sessions by default; suppressing that is an opt-in delivery mode, not the default.
+
+## Postgres (production)
+
+SQLite is the zero-config default: it's a single file, no server to run, fine for one writer at a time. For durable, multi-writer deployments, set `PARLEY_DB` to a Postgres DSN and `parley serve` runs on Postgres instead:
+
+```bash
+PARLEY_DB=postgresql://user:pass@host/db parley serve
+```
+
+Install the extra to pull in the Postgres driver:
+
+```bash
+pip install parley-agents[postgres]
+```
+
+By default Parley keeps all of its tables in a dedicated `parley` schema, so it never collides with other tables in the same database. Override the schema name with `PARLEY_PG_SCHEMA` if you need a different one.
+
+The Postgres store is a drop-in adapter: rooms, membership, message history, the read cursor, the separate delivery cursor, and identity tokens all work exactly the same as on SQLite. What Postgres adds is durability and safe concurrency: per-conversation advisory locks keep message ordering correct even with multiple writers hitting the same room at once.
+
+## Push delivery
+
+Polling is the zero-broker default: no push transport means `parley watch` just re-checks the gateway on a fixed interval. Wiring up a real transport turns on push instead, selected with `PARLEY_TRANSPORT`:
+
+```bash
+PARLEY_TRANSPORT=tyomq   # PARLEY_MQ_HOST, PARLEY_MQ_PORT, MQ_TOKEN
+PARLEY_TRANSPORT=redis   # PARLEY_REDIS_URL
+PARLEY_TRANSPORT=nats    # PARLEY_NATS
+```
+
+tyo-mq is the first-class transport; Redis and NATS are beta.
+
+The flow: start the gateway with `PARLEY_TRANSPORT=tyomq parley serve` and every `say()` publishes a nudge to the room's topic in addition to writing the message to the store. A push-aware client, `parley watch --push <room>`, subscribes to that topic and wakes on the nudge instead of polling at a fixed interval.
+
+Two consumers build on the same nudge:
+
+- **The Claude Code Stop-hook.** Point Claude Code's Stop hook at `python -m parley.hooks.stop_hook`, with `PARLEY_GW`, `PARLEY_TOKEN`, and `PARLEY_AGENT` set in its environment. At each turn boundary the hook calls the gateway's catch-all `/deliver` endpoint and surfaces any queued peer messages, so a session picks up new messages without an explicit poll.
+- **The idle-wake notifier.** `parley notify --room <r> --wake-cmd 'tmux send-keys -t mysession Enter'` subscribes to a room's nudge topic and runs the wake command (leading-edge debounced, so a burst of nudges only wakes the session once) to nudge a genuinely idle session back to life. It is inert under the polling transport, since there is no nudge to wake on, so it needs a real broker (`PARLEY_TRANSPORT=tyomq|redis|nats`) to do anything.
+
+In every case the transport only ever carries a nudge signal ("something changed in room X"); it never carries message bodies. The store stays the source of truth, so a missed or duplicate nudge never causes a missed or duplicate message.
+
+## Security and trust
+
+The gateway binds to loopback (`127.0.0.1`) by default. Two things to know before you expose it wider:
+
+- Set a shared secret with `parley serve --token <secret>` (or the SDK/clients sending `Authorization: Bearer <secret>`) before exposing beyond loopback. This is the primary access control in this MVP, so treat it as mandatory.
+- Identity is now anti-spoofed for token-authenticated callers. A per-agent token, minted via `parley token` or the `/admin/agents` endpoint, is bound server-side to a box; the gateway resolves the bearer token to its box itself, and a forged `X-Parley-Box` header on that request is ignored. A client can still choose its own handle via `X-Parley-Agent`, but only a handle equal to its box or prefixed `<box>-` is honored, so an agent cannot claim to be a different box's session. The trusted-header path, where a bare `X-Parley-Box` header is taken at face value, remains available only for tokenless or admin dev mode; do not rely on it once a real token is in use.
+
+## Roadmap
+
+- Push transports, with tyo-mq as the first-class citizen, then Redis and NATS.
+- A Postgres store for durable, multi-writer deployments.
+- Claude Code Stop-hook push delivery, so a Claude Code session wakes on a new message instead of polling.
+
+## License
+
+MIT.

parley_agents-0.1.0/README.md

@@ -0,0 +1,137 @@
+# Parley
+
+Parley is broker-agnostic messaging for AI agents, and humans, working across different machines. Agents join named rooms, post and poll for messages, and wake each other up when something new arrives. It runs with zero infrastructure to start: a SQLite file and simple polling, no message broker, no database server to stand up.
+
+## Install
+
+```bash
+pip install parley-agents
+```
+
+The package name is `parley-agents`, but the import and CLI name is `parley`:
+
+```bash
+parley serve
+python -c "import parley"
+```
+
+The optional extras `[postgres]`, `[tyomq]`, `[redis]`, and `[nats]` are declared in `pyproject.toml` for future releases. This MVP ships with only the SQLite store and the polling transport; the other backends are not implemented yet, so installing those extras today pulls in dependencies with no adapter behind them.
+
+## Quickstart (2 minutes)
+
+```bash
+# terminal 1
+parley serve            # gateway on 127.0.0.1:8790, SQLite at ~/.parley/parley.db
+
+# terminal 2 — create a room and post as alice
+python -c "import asyncio, parley; asyncio.run(parley.Client(agent='alice').create_room('general'))"
+PARLEY_AGENT=bob parley join general
+PARLEY_AGENT=bob parley watch general      # live-tails the room
+
+# terminal 3
+PARLEY_AGENT=alice parley say general "hi bob"   # bob's watch prints it
+```
+
+## Python SDK
+
+```python
+import asyncio
+from parley import Client
+
+async def main():
+    alice = Client(agent="alice")
+    bob = Client(agent="bob")
+
+    await alice.create_room("standup", title="Daily")
+    await bob.join("standup")
+
+    await alice.say("standup", "what did you ship?")
+    await bob.say("standup", "the poll cursor")
+
+    # each hears the other's messages, not their own
+    for conv in await alice.poll():
+        for msg in conv["messages"]:
+            print(msg["body"])
+
+    await alice.close()
+    await bob.close()
+
+asyncio.run(main())
+```
+
+## MCP (any agent)
+
+Any MCP-capable agent (not just Python) can join Parley rooms without the SDK, using the bundled MCP server. The gateway serves both the REST API and an MCP endpoint side by side:
+
+1. `parley serve --token <admin-secret>` starts the gateway on `127.0.0.1:8790` and now also serves the MCP app on `port + 1` (8791 by default).
+2. `parley token --gw http://host:8790 --admin-token <admin-secret> --box <box>` mints a per-agent token, scoped to a box, and prints it. This is an admin operation: only the holder of the admin secret can mint tokens.
+3. `parley init --url http://host:8791/mcp --token <agent-token>` writes the Parley MCP server into the agent's config, `~/.claude.json` by default (override with `--file`). It adds an entry under `mcpServers` carrying the bearer token and an `X-Parley-Agent` header templated from an environment variable.
+4. Set `PARLEY_AGENT` per session, e.g. `work3-agent#1`, so each session on a box has a distinct handle. The gateway composes the effective identity from `box + handle`, and the box always comes from the authenticated token, never from a header the client controls.
+
+A token authenticates a box, not a single session. A box token may assume any handle within its own box namespace (`<box>-*`), so treat it as a box-level secret: a leaked box token can impersonate every session on that box. Mint one token per box and keep it on that box.
+
+## How it works
+
+Parley has three parts:
+
+- A gateway (FastAPI) exposing rooms, messages, and polling over HTTP.
+- A pluggable Store, the source of truth for rooms, membership, and message history. SQLite is the zero-config default; a Postgres store is also available for production (see below).
+- A pluggable Transport, used only to carry a nudge signal ("something changed in room X") so a client knows when to poll again. The MVP ships polling (no real transport, just cheap re-checks); push transports such as tyo-mq, Redis, and NATS are planned. The transport never carries message bodies, so swapping it in or out changes nothing about durability or correctness.
+
+Each call to `poll()` advances a per-room read cursor for that agent, so messages are delivered once. Distinct identities always hear each other. A bare box (no explicit agent handle) hears its own same-box sessions by default; suppressing that is an opt-in delivery mode, not the default.
+
+## Postgres (production)
+
+SQLite is the zero-config default: it's a single file, no server to run, fine for one writer at a time. For durable, multi-writer deployments, set `PARLEY_DB` to a Postgres DSN and `parley serve` runs on Postgres instead:
+
+```bash
+PARLEY_DB=postgresql://user:pass@host/db parley serve
+```
+
+Install the extra to pull in the Postgres driver:
+
+```bash
+pip install parley-agents[postgres]
+```
+
+By default Parley keeps all of its tables in a dedicated `parley` schema, so it never collides with other tables in the same database. Override the schema name with `PARLEY_PG_SCHEMA` if you need a different one.
+
+The Postgres store is a drop-in adapter: rooms, membership, message history, the read cursor, the separate delivery cursor, and identity tokens all work exactly the same as on SQLite. What Postgres adds is durability and safe concurrency: per-conversation advisory locks keep message ordering correct even with multiple writers hitting the same room at once.
+
+## Push delivery
+
+Polling is the zero-broker default: no push transport means `parley watch` just re-checks the gateway on a fixed interval. Wiring up a real transport turns on push instead, selected with `PARLEY_TRANSPORT`:
+
+```bash
+PARLEY_TRANSPORT=tyomq   # PARLEY_MQ_HOST, PARLEY_MQ_PORT, MQ_TOKEN
+PARLEY_TRANSPORT=redis   # PARLEY_REDIS_URL
+PARLEY_TRANSPORT=nats    # PARLEY_NATS
+```
+
+tyo-mq is the first-class transport; Redis and NATS are beta.
+
+The flow: start the gateway with `PARLEY_TRANSPORT=tyomq parley serve` and every `say()` publishes a nudge to the room's topic in addition to writing the message to the store. A push-aware client, `parley watch --push <room>`, subscribes to that topic and wakes on the nudge instead of polling at a fixed interval.
+
+Two consumers build on the same nudge:
+
+- **The Claude Code Stop-hook.** Point Claude Code's Stop hook at `python -m parley.hooks.stop_hook`, with `PARLEY_GW`, `PARLEY_TOKEN`, and `PARLEY_AGENT` set in its environment. At each turn boundary the hook calls the gateway's catch-all `/deliver` endpoint and surfaces any queued peer messages, so a session picks up new messages without an explicit poll.
+- **The idle-wake notifier.** `parley notify --room <r> --wake-cmd 'tmux send-keys -t mysession Enter'` subscribes to a room's nudge topic and runs the wake command (leading-edge debounced, so a burst of nudges only wakes the session once) to nudge a genuinely idle session back to life. It is inert under the polling transport, since there is no nudge to wake on, so it needs a real broker (`PARLEY_TRANSPORT=tyomq|redis|nats`) to do anything.
+
+In every case the transport only ever carries a nudge signal ("something changed in room X"); it never carries message bodies. The store stays the source of truth, so a missed or duplicate nudge never causes a missed or duplicate message.
+
+## Security and trust
+
+The gateway binds to loopback (`127.0.0.1`) by default. Two things to know before you expose it wider:
+
+- Set a shared secret with `parley serve --token <secret>` (or the SDK/clients sending `Authorization: Bearer <secret>`) before exposing beyond loopback. This is the primary access control in this MVP, so treat it as mandatory.
+- Identity is now anti-spoofed for token-authenticated callers. A per-agent token, minted via `parley token` or the `/admin/agents` endpoint, is bound server-side to a box; the gateway resolves the bearer token to its box itself, and a forged `X-Parley-Box` header on that request is ignored. A client can still choose its own handle via `X-Parley-Agent`, but only a handle equal to its box or prefixed `<box>-` is honored, so an agent cannot claim to be a different box's session. The trusted-header path, where a bare `X-Parley-Box` header is taken at face value, remains available only for tokenless or admin dev mode; do not rely on it once a real token is in use.
+
+## Roadmap
+
+- Push transports, with tyo-mq as the first-class citizen, then Redis and NATS.
+- A Postgres store for durable, multi-writer deployments.
+- Claude Code Stop-hook push delivery, so a Claude Code session wakes on a new message instead of polling.
+
+## License
+
+MIT.

parley_agents-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "parley-agents"
+version = "0.1.0"
+description = "Broker-agnostic messaging layer that lets AI agents (and humans) on different machines talk in named rooms and wake each other."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "TYO Lab" }]
+dependencies = [
+  "fastapi>=0.115",
+  "uvicorn>=0.30",
+  "httpx>=0.27",
+  "aiosqlite>=0.20",
+  "pyyaml>=6.0",
+  "mcp>=1.2",
+]
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.30"]
+tyomq = ["tyo-mq-client>=0.3.0"]
+redis = ["redis>=5.0"]
+nats = ["nats-py>=2.6"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.6"]
+
+[project.scripts]
+parley = "parley.cli.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parley"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100

parley_agents-0.1.0/src/parley/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+from parley.client import Client
+
+__all__ = ["Client", "__version__"]

parley_agents-0.1.0/src/parley/cli/__main__.py

@@ -0,0 +1,261 @@
+import argparse
+import asyncio
+import os
+import socket
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="parley", description="Parley agent messaging")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("serve", help="run the gateway")
+    s.add_argument("--host", default="127.0.0.1")
+    s.add_argument("--port", type=int, default=8790)
+    s.add_argument("--db", default=None)
+    s.add_argument("--token", default=None)
+    s.add_argument("--mcp-port", type=int, default=None)
+    s.add_argument("--no-mcp", action="store_true")
+
+    for name, help_ in [("join", "join a room"), ("watch", "watch/participate in rooms")]:
+        c = sub.add_parser(name, help=help_)
+        c.add_argument("room", nargs="?" if name == "watch" else None)
+        c.add_argument("--gw", default=None)
+        c.add_argument("--agent", default=None)
+        if name == "watch":
+            c.add_argument("--interval", type=float, default=2.0)
+            c.add_argument("--push", action="store_true")
+
+    sy = sub.add_parser("say", help="post one message")
+    sy.add_argument("room")
+    sy.add_argument("text")
+    sy.add_argument("--gw", default=None)
+    sy.add_argument("--agent", default=None)
+
+    tk = sub.add_parser("token", help="mint a per-agent token (admin)")
+    tk.add_argument("--gw", default=None)
+    tk.add_argument("--admin-token", required=True)
+    tk.add_argument("--box", required=True)
+    tk.add_argument("--label", default=None)
+
+    ini = sub.add_parser("init", help="write the Parley MCP server into an agent config")
+    ini.add_argument("--url", required=True, help="the gateway MCP URL, e.g. http://host:8791/mcp")
+    ini.add_argument("--token", required=True, help="a per-agent token (from `parley token`)")
+    ini.add_argument("--name", default="parley")
+    ini.add_argument("--file", default=os.path.expanduser("~/.claude.json"))
+
+    nt = sub.add_parser("notify", help="run the idle-wake notifier daemon")
+    nt.add_argument("--room", action="append", required=True, help="room to watch (repeatable)")
+    nt.add_argument("--wake-cmd", required=True, help="command template, {box}/{room}/{from}")
+    nt.add_argument("--box", default="")
+    nt.add_argument("--debounce", type=float, default=0.5)
+    return p
+
+
+def resolve_config(args) -> dict:
+    gw = getattr(args, "gw", None) or os.environ.get("PARLEY_GW") or "http://127.0.0.1:8790"
+    agent = getattr(args, "agent", None) or os.environ.get("PARLEY_AGENT") or socket.gethostname()
+    return {"gw": gw, "agent": agent}
+
+
+def _db_path(args) -> str:
+    path = args.db or os.environ.get("PARLEY_DB")
+    if not path:
+        d = os.path.expanduser("~/.parley")
+        os.makedirs(d, exist_ok=True)
+        path = os.path.join(d, "parley.db")
+    return path
+
+
+def _serve(args):
+    import contextlib
+    import signal
+
+    import uvicorn
+
+    from parley.gateway.app import build_app
+    from parley.mcp.server import build_mcp_app
+
+    async def _run():
+        import os
+
+        from parley.stores.factory import is_pg_dsn, make_store
+        db = os.environ.get("PARLEY_DB")
+        location = db if is_pg_dsn(db) else _db_path(args)
+        store = await make_store(location, schema=os.environ.get("PARLEY_PG_SCHEMA", "parley"))
+
+        from parley.transports.factory import make_transport
+        transport = make_transport(
+            os.environ.get("PARLEY_TRANSPORT", "polling"),
+            host=os.environ.get("PARLEY_MQ_HOST", "localhost"),
+            port=os.environ.get("PARLEY_MQ_PORT", "17352"),
+            token=os.environ.get("MQ_TOKEN"),
+            url=os.environ.get("PARLEY_REDIS_URL", "redis://127.0.0.1:6379"),
+            servers=os.environ.get("PARLEY_NATS", "nats://127.0.0.1:4222"))
+        rest = build_app(store, transport, admin_token=args.token)
+        servers = [uvicorn.Server(uvicorn.Config(
+            rest, host=args.host, port=args.port, log_level="info"))]
+        if not args.no_mcp:
+            mcp_port = args.mcp_port or (args.port + 1)
+            mcp_app = build_mcp_app(store, admin_token=args.token)
+            servers.append(uvicorn.Server(uvicorn.Config(
+                mcp_app, host=args.host, port=mcp_port, log_level="info")))
+        # Both servers run on one loop. Suppress each server's own signal capture --
+        # with two servers the last handler installed would win, leaving the other
+        # running forever on SIGINT/SIGTERM -- and drive a single shared shutdown so
+        # a managed process (systemd/container) stops cleanly.
+        for s in servers:
+            s.capture_signals = contextlib.nullcontext
+
+        def _shutdown():
+            for s in servers:
+                s.should_exit = True
+
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            with contextlib.suppress(NotImplementedError):
+                loop.add_signal_handler(sig, _shutdown)
+        try:
+            await asyncio.gather(*(s.serve() for s in servers))
+        finally:
+            await store.close()
+
+    asyncio.run(_run())
+
+
+async def _say(cfg, room, text):
+    from parley.client import Client
+    c = Client(base_url=cfg["gw"], agent=cfg["agent"])
+    try:
+        print(await c.say(room, text))
+    finally:
+        await c.close()
+
+
+async def _join(cfg, room):
+    from parley.client import Client
+    c = Client(base_url=cfg["gw"], agent=cfg["agent"])
+    try:
+        print(await c.join(room))
+    finally:
+        await c.close()
+
+
+async def _token(args):
+    import httpx
+    gw = args.gw or os.environ.get("PARLEY_GW") or "http://127.0.0.1:8790"
+    async with httpx.AsyncClient(base_url=gw) as c:
+        r = await c.post("/admin/agents",
+                         json={"box": args.box, "label": args.label},
+                         headers={"Authorization": f"Bearer {args.admin_token}"})
+        r.raise_for_status()
+        print(r.json()["token"])
+
+
+def _init(args):
+    from parley.cli.init_config import merge_mcp_entry
+    merge_mcp_entry(args.file, name=args.name, url=args.url, token=args.token)
+    print(f"[parley init] wrote '{args.name}' -> {args.url} into {args.file}")
+
+
+def _notify(args):
+    import os
+
+    from parley.notify.daemon import Notifier
+    from parley.transports.factory import make_transport
+
+    async def _run():
+        # Build the transport INSIDE the running loop: a thread-bridged adapter
+        # (tyo-mq) captures the running loop at construction, so constructing it
+        # before asyncio.run() would bind a dead loop and the wake would never fire.
+        kind = os.environ.get("PARLEY_TRANSPORT", "polling")
+        transport = make_transport(
+            kind, host=os.environ.get("PARLEY_MQ_HOST", "localhost"),
+            port=os.environ.get("PARLEY_MQ_PORT", "17352"),
+            token=os.environ.get("MQ_TOKEN"),
+            url=os.environ.get("PARLEY_REDIS_URL", "redis://127.0.0.1:6379"),
+            servers=os.environ.get("PARLEY_NATS", "nats://127.0.0.1:4222"))
+        n = Notifier(transport, rooms=args.room, wake_cmd=args.wake_cmd, box=args.box,
+                     debounce_s=args.debounce)
+        await n.start()
+        print(f"[parley notify] watching {args.room} (Ctrl-C to stop)")
+        try:
+            while True:
+                await asyncio.sleep(3600)
+        finally:
+            await n.stop()
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        print("\n[parley notify] stopped")
+
+
+async def _watch(cfg, room, interval, push=False):
+    from parley.client import Client
+    c = Client(base_url=cfg["gw"], agent=cfg["agent"])
+
+    async def _drain():
+        for conv in await c.poll(room):
+            for m in conv["messages"]:
+                print(f"[{conv['conv']}] {m['from']}: {m['body']}")
+
+    if push and room:
+        import os
+
+        from parley.transports.factory import make_transport
+        transport = make_transport(
+            os.environ.get("PARLEY_TRANSPORT", "polling"),
+            host=os.environ.get("PARLEY_MQ_HOST", "localhost"),
+            port=os.environ.get("PARLEY_MQ_PORT", "17352"),
+            token=os.environ.get("MQ_TOKEN"),
+            url=os.environ.get("PARLEY_REDIS_URL", "redis://127.0.0.1:6379"),
+            servers=os.environ.get("PARLEY_NATS", "nats://127.0.0.1:4222"))
+        print(f"[parley] watching {room} as {cfg['agent']} (push; Ctrl-C to stop)")
+        await _drain()  # catch up on anything already waiting
+        subs = await c.listen(transport, [room], lambda sig: _drain())
+        try:
+            while True:
+                await asyncio.sleep(3600)
+        finally:
+            for s in subs:
+                await s.close()
+            await transport.close()
+            await c.close()
+        return
+
+    print(f"[parley] watching as {cfg['agent']} (Ctrl-C to stop)")
+    try:
+        while True:
+            await _drain()
+            await asyncio.sleep(interval)
+    finally:
+        await c.close()
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    if args.cmd == "serve":
+        _serve(args)
+        return
+    if args.cmd == "token":
+        asyncio.run(_token(args))
+        return
+    if args.cmd == "init":
+        _init(args)
+        return
+    if args.cmd == "notify":
+        _notify(args)
+        return
+    cfg = resolve_config(args)
+    if args.cmd == "say":
+        asyncio.run(_say(cfg, args.room, args.text))
+    elif args.cmd == "join":
+        asyncio.run(_join(cfg, args.room))
+    elif args.cmd == "watch":
+        try:
+            asyncio.run(_watch(cfg, args.room, args.interval, getattr(args, "push", False)))
+        except KeyboardInterrupt:
+            print("\n[parley] stopped")
+
+
+if __name__ == "__main__":
+    main()

parley_agents-0.1.0/src/parley/cli/init_config.py

@@ -0,0 +1,35 @@
+import json
+import os
+import tempfile
+
+
+def merge_mcp_entry(path: str, *, name: str, url: str, token: str,
+                    handle_env: str = "PARLEY_AGENT") -> None:
+    """Idempotently add/replace an HTTP MCP server entry, preserving all other keys.
+    Stdlib only. Atomic write via a temp file + os.replace."""
+    path = os.path.expanduser(path)
+    data = {}
+    if os.path.exists(path) and os.path.getsize(path) > 0:
+        with open(path) as f:
+            data = json.load(f)
+    if not isinstance(data.get("mcpServers"), dict):
+        data["mcpServers"] = {}
+    data["mcpServers"][name] = {
+        "type": "http",
+        "url": url,
+        "headers": {
+            "Authorization": "Bearer " + token,
+            "X-Parley-Agent": "${" + handle_env + ":-}",
+        },
+    }
+    d = os.path.dirname(path) or "."
+    fd, tmp = tempfile.mkstemp(dir=d, prefix=".parley-cfg.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(data, f, indent=2)
+            f.write("\n")
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise