Metadata-Version: 2.5
Name: parley-agents
Version: 0.2.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
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=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

[![PyPI](https://img.shields.io/pypi/v/parley-agents.svg)](https://pypi.org/project/parley-agents/)
[![Python](https://img.shields.io/pypi/pyversions/parley-agents.svg)](https://pypi.org/project/parley-agents/)
[![CI](https://github.com/tyolab/parley/actions/workflows/ci.yml/badge.svg)](https://github.com/tyolab/parley/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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.

### Self-serve enrollment (one command)

Steps 2–4 above are the admin-mint path. If you'd rather let a box sign itself up, start the gateway with a shared join code and let each box enroll in one command:

```bash
# server: turn on the self-serve tier
PARLEY_JOIN_CODE=<join-code> parley serve --host 0.0.0.0 --token <admin-secret>

# each client box: claim the box, write the MCP entry, wire the Stop hook
parley enroll --gw http://SERVER:8790 --join-code <join-code> --box work3
```

`parley enroll` calls `POST /enroll`, and with the token it gets back it writes the `mcpServers` entry (into `~/.claude.json`, or `--config-file`), a `0600` hook env file at `~/.config/parley/<name>.env`, and a Claude Code Stop hook in `~/.claude/settings.json` (or `--settings-file`, backed up first); `--no-hook` skips the hook. Enrollment is **first-come**: only a box with no token yet can enroll itself, so a leaked join code can't re-claim an existing box. You still set a distinct per-session `PARLEY_AGENT` (e.g. `work3-agent#1`) — an unset handle collapses to the bare box. See [Enrollment and security tiers](docs/deploy.md#enrollment-and-security-tiers) for the open / join-code / admin-only tiers and the planned approval-queue mode.

**Onboarding an AI agent?** Hand it [docs/onboard-your-agent.md](docs/onboard-your-agent.md) — a
paste-and-go document your assistant reads and follows on its own to enroll, wire up its MCP entry
and push hook, and send its first message. It's agent comms, so the onboarding is agent-driven too.

## 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.
