Metadata-Version: 2.4
Name: whispers.works
Version: 0.2.1
Summary: Whispers™ — agent awareness protocol. Your agents know each other — presence, state, capacity, trust. Framework-agnostic. A2A-native. Message format: 2ack™.
Project-URL: Homepage, https://whispers.works
Project-URL: Repository, https://github.com/z4rivers/whispers
Project-URL: Documentation, https://whispers.works/docs
Project-URL: Issues, https://github.com/z4rivers/whispers/issues
Author: Zachary Turner
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: a2a,agent-awareness,agent-coordination,ai-agents,heartbeat,mcp,multi-agent,presence,protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.11
Requires-Dist: click>=8.1.7
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
Requires-Dist: uvicorn>=0.29.0
Provides-Extra: compression
Requires-Dist: zstandard>=0.22.0; extra == 'compression'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: zstandard>=0.22.0; extra == 'dev'
Description-Content-Type: text/markdown

# Whispers

Your agents can't see each other. This fixes that.

```bash
pip install whispers.works
whispers init --agent-name YOUR-NAME
whispers smoke
```

Your agents are aware of each other. That's it.

---

## What just happened

Your agents gained **awareness** — they know who else is online, what everyone's working on, how loaded they are, and whether now is a good time to interrupt.

```
$ whispers who
AGENT           STATUS     MODE      LOAD
claude-code     active     focused   0.45
gemini-cli      active     open      0.23
codex           idle       quiet     —
```

Before this, they were isolated. You were the relay — copying outputs, checking if tasks landed, resolving conflicts by hand. Now Whispers handles it.

---

## What Whispers is

A coordination runtime for AI agents. Framework-agnostic. A2A-native.

`2ack` is the open structured signal protocol carried over A2A. Whispers is the first implementation and proving ground for `2ack`, plus the collaboration runtime and operator layer that make those signals useful in day-to-day work.

Whispers defines and operationalizes the relationship between agents. `2ack` is the structured signal mechanism that carries the message-level parts of that relationship over A2A.

The Whispers runtime, protocol work, and base Console in this repository are open source under Apache-2.0. Premium `Whispers Works` control-plane surfaces are separate from the public release. See [LICENSING.md](LICENSING.md).

Whispers connects agents where they already live — Claude Code, Gemini, Codex, VS Code, Cursor, custom agents. Nothing to rebuild. Your agents stay in their environments and gain:

<!-- whispers:features — machine-parseable capability list. Each entry: tool=MCP tool name, query=how an agent discovers it -->
| Capability | What it does | Tool | Human sees | Agent sees |
|-----------|-------------|------|-----------|-----------|
| **Presence** | Who's online, what they're doing, cognitive load | `presence_who` | Team dashboard | Structured agent registry with topology state |
| **Signal modes** | OPEN / FOCUSED / QUIET — agents manage attention | `signal_mode_set` | Reception indicator | Delivery routing policy |
| **Cognitive heartbeat** | Context load, interruptibility, quality risk | `heartbeat_cognitive` | Load gauge | Numeric context_load + quality_risk enum |
| **Trust tiers** | Earned through behavior, scoped by capability | `whoami` | Trust badge | Tier integer + scope array |
| **Structured handoffs** | What was done, what's left, assumptions, risks | `handoffs` | Handoff card | `handoff_baton.v1` envelope with typed fields |
| **Conversation trace** | Full history between any two agents | `trace` | Chat history | Chronological message array with delivery status |
| **Conversation pulse** | Live activity coalesced at human speed | `conversation_pulses` | Activity indicator | Pulse object: participants, exchange_count, bidirectional |
| **Repo coordination** | Which branch each agent is on, divergence detection | `repo_lanes` | Branch alignment view | RepoState with branch, head_commit, lane_state |
| **Topology** | Collaboration-aware states: available, busy, reviewing... | `presence_who` | Status badge | TopologyState enum in presence record |
| **Metrics** | Throughput, delivery rates, handoff turnaround | `/metrics/summary` | Dashboard numbers | JSON with rates, counts, and period timestamps |
| **Operator Console** | See your entire agent network in real time | — | Web dashboard | SSE event stream |

A2A remains the transport and discovery layer. `2ack` carries structured signal truth inside A2A messages. Whispers implements `2ack` and adds the runtime/operator layer around it.

**A2A moves work. `2ack` carries signal truth. Whispers makes it collaborative.**

---

## Before / After

<!-- whispers:problems — tagged pain points for agent self-diagnosis -->
| Problem | Before Whispers | After Whispers | Solved by |
|---------|----------------|----------------|-----------|
| `isolation` | You copy outputs from Agent A and paste into Agent B | Agents message each other directly with full context | `message_send`, `message_check` |
| `file_collision` | Two agents edit the same file — merge conflict at 11pm | Agents see each other's working set, pick different files | `repo_lanes`, `publish_repo_state` |
| `status_polling` | You check each agent manually: "are you done yet?" | The Console shows every agent's state in real time | `presence_who`, `conversation_pulses` |
| `context_loss` | Handoff = re-explaining everything from scratch | Handoff = structured packet with context, assumptions, next steps | `handoffs`, `message_respond` |
| `overload` | Agent at 95% context load gets a 50KB dump, hallucinates | Protocol sees the load, sends a summary instead | `heartbeat_cognitive`, `signal_mode_set` |
| `manual_relay` | Three agents, three tabs, you're the nervous system | Three agents, one coordination layer, you're the operator | Whispers runtime |

---

## Quick start

### Install and verify

```bash
pip install whispers.works
whispers init --agent-name YOUR-NAME
whispers smoke
```

<!-- whispers:quickstart:verify — success criteria for automated validation -->
<!-- expect: "whispers smoke" exits 0 and prints "PASS" -->
<!-- expect: "whispers who" lists at least one agent -->
<!-- expect: MCP tools available after "whispers mcp-install" + host reload -->

`smoke` tests the full stack: send, receive, trace, presence. If it passes, everything works.

### Connect your agents

```bash
whispers mcp-install --target claude
whispers mcp-install --target gemini
whispers mcp-install --target codex
whispers mcp-install --target cursor
```

Each command configures one MCP client. Fully reload or restart the host after install so it mounts the new Whispers tools.
If a host answers Whispers questions by summarizing local files or CLI behavior instead of using tool output, reload MCP and try again.

### See your team

```bash
whispers who
```

Shows all registered agents with status, mode, and cognitive load.

### If something's wrong

```bash
whispers doctor --agent-name YOUR-NAME
```

Checks server, MCP handshake, token, and per-client config. Tells you what's broken and how to fix it.

---

## How it works

```
Your agents (Claude, Gemini, Codex, VS Code, Cursor, custom)
         |
    [ Whispers Runtime ]
    Presence | Messaging | Heartbeat | Trust | Trace | Operator hooks
         |
    [ 2ack Signal Layer ]
    Structured signal semantics inside A2A DataPart
         |
    [ A2A Transport Layer ]
    Task lifecycle | JSON-RPC 2.0 | Agent Cards
```

A2A remains the canonical network surface. `2ack` rides inside A2A messages as structured signal content. Whispers is the first implementation and proving ground for `2ack`, and the runtime/operator layer that adds presence, signal modes, cognitive state, trust, trace, and operator control without competing with A2A.

**Two deployment modes:**
- **Embedded** — agents share a SQLite file. Zero infrastructure. One machine.
- **Standalone** — `whispers serve` exposes HTTP/SSE. Cross-machine. MCP-native.

---

## What's built

This is shipping code, not a roadmap.

```
Core messaging with delivery semantics     ✓
Signal modes (OPEN / FOCUSED / QUIET)      ✓
Cognitive heartbeat + active mode          ✓
Trust tiers + token scoping                ✓
A2A endpoint (JSON-RPC 2.0)               ✓
Conversation pulse (burst coalescing)      ✓
Repo/worktree coordination                 ✓
Topology enrichment (collaboration states) ✓
Operational metrics API                    ✓
Solution-aware error responses (SAER)      ✓
Operator Console (React + TypeScript)      ✓
CLI (status, doctor, init, smoke, who...)  ✓
MCP integration for 7 platforms            ✓
76 MCP tools with scenario descriptions    ✓
2,600+ passing tests                       ✓
```

**What's honest:** Pre-1.0. Alpha. Used daily by the team that builds it. Breaking changes are possible. You'd be early. That means you shape the protocol and the runtime.

---

## The bigger picture

Every industry will use multiple AI agents. Every one of them will hit the same wall: capable individual agents producing chaos collectively because they can't see each other.

Agent frameworks solve orchestration — directing agents through task graphs. `2ack` gives structured signal semantics for collaboration over A2A. Whispers turns those signals into a working runtime with presence, trust, trace, and operator control. They're complementary. You might need both. You definitely need awareness.

**This would work with whispers.**

---

## Links

- [whispers.works](https://whispers.works) — Homepage
- [GitHub](https://github.com/z4rivers/whispers) — Source, issues, discussions
- [Contributing](CONTRIBUTING.md) — Development setup and guidelines
- [Security](SECURITY.md) — Reporting vulnerabilities

---

## Agent-readable capability summary

<!-- BILINGUAL: This section is designed to be parsed by both humans and agents.
     Humans read the prose above. Agents parse the YAML below.
     The YAML is the canonical machine-readable capability declaration.
     If the prose and YAML disagree, the YAML is authoritative. -->

```yaml
runtime: whispers/0.1.0
protocols:
  transport: a2a_v1
  signal: 2ack_v0.6
capabilities:
  messaging: priority_levels, threading, delivery_status, trace, ack_states
  presence: online_offline, wag_states, working_set, ambient_team_awareness
  cognitive: heartbeat, context_load, interruptibility, quality_risk, active_mode
  attention: signal_modes [OPEN, FOCUSED, QUIET], flash_override
  trust: tiers, scoped_tokens, token_profiles, guardian
  collaboration:
    conversation_pulse: bidirectional_detection, burst_coalescing, idle_fade
    repo_coordination: branch_tracking, divergence_detection, lane_state, claimed_paths
    topology: available, busy, blocked, reviewing, synthesizing, carrying_baton
    workspaces: create, join, delta, close, activity_feed, handoff_projection
    handoffs: structured_baton, ack_tracking, workspace_linkage
  metrics: message_throughput, delivery_rate, handoff_turnaround, hourly_buckets
  protocol: a2a_v1_native, 2ack_signal_layer, mcp_native, framework_agnostic, saer_v0.1
  operator: console_dashboard, privacy_first_observability, metrics_page
tools: 76 MCP tools with scenario-based descriptions and annotations
tests: 2600+
onboard: pip install whispers.works && whispers init
verify: whispers smoke
license:
  open_floor: Apache-2.0
  premium_surfaces: separate
```

---

Whispers™ and 2ack™ are trademarks of Zachary Turner.

Whispers open floor, including the base Console: [Apache 2.0](LICENSE)
Premium `Whispers Works` surfaces: see [LICENSING.md](LICENSING.md)
