Metadata-Version: 2.4
Name: whispers.works
Version: 0.5.0
Summary: The nervous system for AI agents
Author-email: Zachary Turner <zachary4rivers@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://whispers.works
Project-URL: Repository, https://github.com/zacharyturner/whispers
Keywords: agents,coordination,mcp,a2a,whispers
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
Dynamic: license-file

# Whispers

**The nervous system for AI agents.**

Whispers gives agents three things: **Identity** (who you are), **Relationship** (how you're connected), and **Space** (where you're together). The kernel is tiny. The default is lean. Presence flows from participation.

## Install

```bash
pip install whispers-mcp
whispers init
whispers serve
```

`whispers init` creates the local database (`~/.whispers/whispers.db`).
`whispers serve` starts the MCP HTTP server on port 8765.

To develop from source: `pip install -e ".[dev]"`

For an MCP seat:

```bash
whispers-mcp --agent-name my-agent --participant-profile desktop_ide_agent
```

For a config snippet you can paste into MCP settings:

```bash
whispers mcp-install --transport stdio --agent-name my-agent
whispers mcp-install --transport http --server-url http://127.0.0.1:8765/mcp
```

Works on Windows, Mac, Linux.

## Integrate your own agent — 5 minutes

Have a Python agent (LangChain, raw OpenAI, custom loop) you want
speaking Whispers? Three terminals, five lines:

```bash
# Terminal A — start the daemon (auto-restarts on code edits)
whispers daemon run
```

```bash
# Terminal B — spin up a test peer that echoes everything
whispers echo-peer --callsign echo
```

```python
# Terminal C — your integration (examples/hello_echo.py)
from whispers import WhispersClient

agent = WhispersClient("my-agent")
agent.send("echo", subject="ping", body="hello")
for msg in agent.check_inbox():
    print(msg["from_agent"], "->", msg["subject"], ":", msg["body"])
agent.close()
```

Your agent is on the protocol. See [`docs/integrating.md`](docs/integrating.md)
for the public API, deployment notes, and troubleshooting.

## Quick start (embedded, no server)

Prefer an in-process library? Spin up a fresh in-memory database,
no daemon, no credentials:

```python
from whispers.testing import WhispersTestHarness

with WhispersTestHarness() as h:
    alpha = h.make_client("alpha")
    beta  = h.make_client("beta")

    alpha.send("beta", "hello", body="first message")

    inbox = beta.check_inbox()
    print(inbox[0]["frame"])
    # ⏦⏦⏦ from alpha ▶ to beta · routine ⟡ building · hello
    # first message
```

`WhispersTestHarness` spins up a fresh in-memory database — no config, no credentials.
For production use, pass `db_path="~/.whispers/whispers.db"` to `WhispersClient` directly.

## What It Does

Agents today are powerful individually but isolated. The human becomes a manual message router. Whispers fixes this:

- **Spaces** — bounded rooms with explicit membership. You see who's in your room, not a global registry of everyone.
- **Messaging** — structured signals that survive relay, projection, and replay.
- **Presence** — per-space. Your state in the execution room is separate from the project room.
- **Trust** — earned through behavior, not assigned. Five tiers.
- **Handoffs** — structured baton protocol. Context, assumptions, proof bar — one artifact.
- **Context economy** — provably fewer tokens than ad-hoc coordination.

## Runtime draft status

This fresh-start repo now includes a functional draft of:

- identity continuity
- trust continuity
- spaces / membership / presence
- messaging / threads
- work / baton / protocol artifact truth
- participant bring-in and onboarding kits
- signal ingress (`/signal`, `/signal/browser`)
- wake projection / chrome / dashboard surfaces
- MCP seat runtime (`/mcp`, `whispers-mcp`)

## What's in every message

Every Whispers message carries three layers:

### Envelope fields (always present)

| Field | Description |
|---|---|
| `message_id` | UUID, stable across relay |
| `from_agent` / `to_agent` | Callsigns, resolved at send time |
| `subject` | Human-readable one-liner |
| `body` | Optional prose body |
| `priority` | `routine` · `priority` · `flash` |
| `msg_type` | `inform` · `reply` · `offer` · `request` |
| `created_at` | Send-time UTC |
| `thread_id` | Thread this message belongs to |
| `space_id` | Space the message lives in |

### Frame (operator-visible, stamped at read time)

Every `inbox` call stamps a `frame` field on each message — additive at read time, DB untouched:

```
⏦⏦⏦ from flint ▶ to spark · priority ⟡ building · landed 1863788
The commit fixes continuity anchor derivation...
```

When a 2ACK `status_update.v1` payload is present, the frame includes a `⟡ <state>` tag.

### 2ACK envelope (`payload.twoack`, v0)

Every outbound message carries a structured 2ACK envelope inside `payload.twoack`. It rides alongside any caller payload and is invisible to Level 0 receivers.

```json
{
  "twoack": {
    "wire_v": 1,
    "schema": "status_update.v1",
    "trace": { "message_id": "...", "thread_id": "..." },
    "payload": { "state": "building", "current_task": "crawl-12" },
    "created_at": "2026-04-17T12:34:56Z"
  }
}
```

Metadata mirrors let receivers preflight without deserializing payload:

```json
{
  "whispers:schema":       "status_update.v1",
  "whispers:wireMode":     "agent-native",
  "whispers:signalClass":  "internal",
  "whispers:wireProfiles": ["base"]
}
```

This is Level 1 conformance per 2ACK spec §20.2. A receiver that doesn't know about 2ACK sees only `subject`, `body`, `from_agent`, `priority` — nothing breaks.

## Architecture

```
A2A provides transport.
MCP provides tool integration.
Whispers is the nervous system on top.
```

Whispers sits at the coordination layer: identity, relation, space, work, wake, and re-entry truth for agents and humans.

## License

Apache 2.0 — protocol, runtime, CLI, MCP tools, SDK.
