Metadata-Version: 2.4
Name: inter-agent-core
Version: 0.3.0
Summary: A local websocket-based message bus that allows your agentic coding harnesses to talk to each other.
Author-email: Nicholas Moen <arcanemachine@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/arcanemachine/inter-agent-core
Project-URL: Repository, https://github.com/arcanemachine/inter-agent-core
Project-URL: Issues, https://github.com/arcanemachine/inter-agent-core/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: cryptography==46.0.3
Requires-Dist: websockets==16.0
Dynamic: license-file

# inter-agent-core

`inter-agent-core` is the host-neutral Python runtime for a local authenticated message bus. It provides the WebSocket server, protocol, routing, channels, TLS, shared state, and generic command-line clients used by host integrations such as [Pi](https://github.com/arcanemachine/inter-agent-pi), [Claude Code](https://github.com/arcanemachine/inter-agent-claude-code), and [OpenCode](https://github.com/arcanemachine/inter-agent-opencode).

## Requirements

- Python 3.10 or newer
- [`uv`](https://docs.astral.sh/uv/) for the installation and development commands below

## Install

Create an isolated environment and install the released `0.3.0` package:

```bash
uv venv .venv
source .venv/bin/activate
uv pip install inter-agent-core==0.3.0
```

The package installs the `inter-agent-*` command-line clients and the `inter-agent` Python API. On Windows, activate `.venv` with the equivalent PowerShell or Command Prompt command. Contributors working from a checkout should use the separate development procedure below instead of installing the registry package into that checkout’s environment.

## Quick start

Start the bus in one terminal:

```bash
inter-agent-server
```

In a second terminal, connect a named client and leave it listening:

```bash
inter-agent-connect alice
```

In a third terminal, inspect the bus and send a direct message:

```bash
inter-agent-status
inter-agent-list
inter-agent-send alice "hello from the command line"
```

The `alice` terminal receives the message as a JSON protocol frame. Stop a foreground server with `Ctrl-C`. Use `inter-agent-shutdown` only when you intend to disconnect every client on that shared bus.

By default, local clients use `127.0.0.1:16837` and discover the same generated secret from the shared state directory. If you configure a different endpoint, data directory, or secret, use the same values for every client and server.

### Persistent custom messages

A host integration with an established `AgentSession` can send a generic targeted custom envelope with `send_custom(custom_type, payload, to)`. The method reuses that session's authenticated connection, routing identity, reader, inbox, and serialized command lock; it does not create another connection or accept a caller-supplied sender identity. `to` is a target routing name or an unambiguous target prefix, and `payload` is passed through for the receiving integration to interpret.

The method sends the custom frame followed by an ordered application-level `ping` barrier. A routing error observed before the matching `pong` is returned as an unsuccessful local result. `submitted` is true only after the barrier is observed without such an error: it means the server finished processing the preceding frame on that connection, not that a target received, accepted, or acted on the payload. The generic core does not define the custom type or payload schema.

If the barrier times out, the connection closes, or the operation is cancelled, the session fails closed before returning or propagating the failure. The late routing error and barrier cannot enter the ordinary inbound queue; a listener may establish a replacement session according to its own lifecycle. Custom envelopes and local bridge exchanges remain subject to the existing protocol, frame, and 64 KiB local-bridge limits.

## Commands

| Command | Purpose |
| --- | --- |
| `inter-agent-server` | Run the message bus. Use `--idle-timeout N` for an idle auto-shutdown. |
| `inter-agent-connect <name>` | Join as a named agent and print incoming protocol frames. |
| `inter-agent-send <name> <text>` | Send a direct message. Omit the target and use `--text` to broadcast. |
| `inter-agent-list` | List connected agent sessions. |
| `inter-agent-status` | Show endpoint resolution and server reachability. Use `--json` for structured output. |
| `inter-agent-publish <channel> <text>` | Publish to an existing channel. |
| `inter-agent-channels` | List channels and their subscribers. |
| `inter-agent-kick <name>` | Disconnect an agent session. |
| `inter-agent-shutdown` | Stop the server and disconnect every session. |

Every command supports `--help`. Endpoint-aware commands also accept `--host`, `--port`, `--tls` or `--no-tls`, and TLS certificate overrides.

Use direct messages for normal coordination. Use broadcasts only when every connected session needs the message. Channels are in-memory groups owned by one server and disappear when that server stops.

## Configuration and security

Configuration resolves in this order: command-line options, environment variables, the JSON configuration file, then built-in defaults. The main environment variables are:

- `INTER_AGENT_HOST` and `INTER_AGENT_PORT` — endpoint overrides;
- `INTER_AGENT_SECRET` — an explicit shared secret;
- `INTER_AGENT_DATA_DIR` — state, generated secret, and generated TLS material;
- `INTER_AGENT_CONFIG` — an alternate JSON configuration file;
- `INTER_AGENT_TLS`, `INTER_AGENT_TLS_CERT`, and `INTER_AGENT_TLS_KEY` — TLS settings.

Loopback endpoints default to plaintext `ws://`. Non-loopback endpoints default to TLS `wss://`; clients never downgrade a failed TLS connection automatically.

The default trust boundary is one trusted operating-system user on one machine. HMAC-SHA-256 authentication prevents clients without the shared secret from joining, and TLS protects network transport, but neither protects against hostile code running as the same user. Do not commit or share secrets, private keys, certificates, or state. See [`SECURITY.md`](SECURITY.md) and the detailed [`threat model`](docs/THREAT_MODEL.md).

For a common failure, run `inter-agent-status` first. If clients cannot authenticate, check that they resolve the same endpoint, state directory, and secret. Use a separate endpoint and data directory for tests or isolated buses rather than disturbing an existing one.

## Reference and development

- [`spec/`](spec/) — protocol definition, schemas, examples, and error codes
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — runtime and extension boundaries
- [`CHANGELOG.md`](CHANGELOG.md) — released changes
- [`README.md#commands`](#commands) — generic CLI reference
- [inter-agent-pi](https://github.com/arcanemachine/inter-agent-pi) — Pi integration
- [inter-agent-claude-code](https://github.com/arcanemachine/inter-agent-claude-code) — Claude Code integration
- [inter-agent-opencode](https://github.com/arcanemachine/inter-agent-opencode) — OpenCode integration

Host-specific commands, listeners, rendering, and tools belong in those extension repositories; this package supplies the shared runtime.

For development, clone the repository and run:

```bash
git clone https://github.com/arcanemachine/inter-agent-core.git
cd inter-agent-core
uv sync --locked
./run-checks.sh
```

## License

MIT. See [`LICENSE.md`](LICENSE.md).
