3tears-channels

A unified message protocol for the 3tears framework, with adapters for Slack, Discord, and WebSocket clients. Write your agent logic once and deliver it across channels.

pip install 3tears-channels

What you get

One message model -- ChannelMessage, ChannelResponse, ChannelDeliveryMessage, and Attachment carry a request and its reply regardless of channel.
Routing -- ChannelRouter and StreamingChannelRouter dispatch inbound messages and stream responses back.
Slack and Discord -- payload and rich-formatting builders (build_slack_blocks, build_slack_payload, build_discord_embed, build_discord_payload) plus a should_use_rich_formatting helper.
WebSocket -- WebSocketHandler, WebSocketProtocol, a ConnectionRegistry, and frame primitives for real-time clients.
Rooms and presence -- RoomFanout, RoomState, RoomIndexCollection, and a three-tier-backed PresenceCollection with a PresenceSweeper for connection liveness.
Email -- threetears.channels.mail: Mailer over an EmailTransport, an SMTP transport reading its settings per send, EmailTemplate substitution with an HTML alternative and List-Unsubscribe headers, send_batch for many recipients with per-recipient failure isolation, and BounceReceiver for HMAC-verified delivery reports. A sibling of the channel adapters rather than one of them -- an email recipient has no conversation and usually no account, so ChannelDeliveryMessage does not apply.

Quickstart

from threetears.channels import ChannelRouter, ChannelMessage, build_slack_blocks

router = ChannelRouter(...)
response = await router.dispatch(ChannelMessage(text="hello", channel="slack", ...))

blocks = build_slack_blocks(response)

WebSocket connection lifetime

WebSocketHandler ends a connection on its own in two cases, besides the peer disconnecting.

The peer stops answering. Every heartbeat_interval seconds (config key, default 30) each open connection is sent {"type": "ping"}. A connection that has sent nothing since the previous ping is closed with code 1011, and its registry entry, rooms and presence are cleaned up as on a disconnect. Any frame counts as an answer; an otherwise idle client answers with {"type": "pong"}. A connection busy with a frame (a turn in flight) is not judged until it is reading again.

The credential expires. If the auth_validator's claims include exp (unix seconds), the first frame at or after that time, or the first heartbeat tick of an idle connection, is answered with the same refusal an unauthenticated connection gets:

{"type": "error", "code": "UNAUTHENTICATED", "message": "access token expired"}

and the socket is closed 1008. A client handles it like any UNAUTHENTICATED refusal: obtain a fresh credential and reconnect. Leave exp out of the claims for a connection that should not expire.

A connection that is answering pings also keeps its presence row fresh, so PresenceSweeper does not evict a live member.

License

MIT. See LICENSE.

Metadata

Release files for 3tears-channels 0.65.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for 3tears-channels 0.65.0
File	Size	Uploaded
3tears_channels-0.65.0.tar.gz	193.3 kB	Oct 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for 3tears-channels 0.65.0
File	Interpreter	ABI	Platform	Reset
3tears_channels-0.65.0-py3-none-any.whl 110.0 kB Oct 5, 2026	Python 3	none	any	Details

Total release size: 303.3 kB

Release files / 3tears_channels-0.65.0.tar.gz

Download URL	3tears_channels-0.65.0.tar.gz
Size	193.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`be37f27b86772a7d7a90c5a01e0390d787e521ffc465eeaa1544a8ca66c51c25`
BLAKE2b-256 checksum How to use checksums	`c4182134f5b2ea5a14cef5313c4d257cba9135062fc40a98553e082adb6f483e`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/pacepace/3tears
Publishing commit: github.com/pacepace/3tears/tree/266ff3be98b3d1d25d316fbab5c70363aba549c0

Workflow

Publishing configuration: github.com/pacepace/3tears/blob/266ff3be98b3d1d25d316fbab5c70363aba549c0/.github/workflows/release.yml
Publishing logs: github.com/pacepace/3tears/actions/runs/37286444328/attempts/1

Artifact

Subject: 3tears_channels-0.65.0.tar.gz
SHA-256 checksum: be37f27b86772a7d7a90c5a01e0390d787e521ffc465eeaa1544a8ca66c51c25 Verifying attestations

Release files / 3tears_channels-0.65.0-py3-none-any.whl

Download URL	3tears_channels-0.65.0-py3-none-any.whl
Size	110.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`bd99c2e285504e495af89e0ee97d803213b48f1c136e23a0bccbb6b977be5c46`
BLAKE2b-256 checksum How to use checksums	`2063457c2ec6db49b5bef86c96a7431658209c97f336c6dd129dd52177f8935f`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/pacepace/3tears
Publishing commit: github.com/pacepace/3tears/tree/266ff3be98b3d1d25d316fbab5c70363aba549c0

Workflow

Publishing configuration: github.com/pacepace/3tears/blob/266ff3be98b3d1d25d316fbab5c70363aba549c0/.github/workflows/release.yml
Publishing logs: github.com/pacepace/3tears/actions/runs/37286444328/attempts/1

Artifact

Subject: 3tears_channels-0.65.0-py3-none-any.whl
SHA-256 checksum: bd99c2e285504e495af89e0ee97d803213b48f1c136e23a0bccbb6b977be5c46 Verifying attestations