Metadata-Version: 2.4
Name: tundish
Version: 0.1.2
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
License-File: LICENSE
Summary: A local inbox that agents subscribe to
Home-Page: https://github.com/cjohnhanson/tundish
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/cjohnhanson/tundish

# tundish

tundish is a local inbox for agents. Programs publish JSON items into named
queues in one SQLite file. A subscription filters the items and renders them
as text for a subscriber. A hook runs `tundish pull` and injects the printed
text into the agent's session.

## Install

The command is `tundish`, whichever package you install.

**[Archives of precompiled binaries for macOS and
Linux](https://github.com/cjohnhanson/tundish/releases)** cover x86-64 and
arm64. The Linux binaries are static executables. Each archive holds the
binary, its man pages, the README and the license. There is no Windows build.

| Package manager | Package | Command |
| --- | --- | --- |
| [Homebrew](https://brew.sh) | [cjohnhanson/tap/tundish](https://github.com/cjohnhanson/homebrew-tap) | `brew install cjohnhanson/tap/tundish` |
| [Cargo](https://doc.rust-lang.org/cargo/) | [tundish](https://crates.io/crates/tundish) | `cargo install tundish` |
| [uv](https://docs.astral.sh/uv/) | [tundish](https://pypi.org/project/tundish/) | `uv tool install tundish` |
| [pip](https://pip.pypa.io/) | [tundish](https://pypi.org/project/tundish/) | `pip install tundish` |
| [npm](https://www.npmjs.com) | [tundish](https://www.npmjs.com/package/tundish) | `npm install -g tundish` |
| [Nix](https://nixos.org/) | [flake](flake.nix) | `nix profile install github:cjohnhanson/tundish` |

### Building from source

tundish is written in Rust. It needs Rust 1.88 or newer and a C compiler
for the bundled SQLite library. The repository pins a toolchain in
`rust-toolchain.toml`.

```sh
git clone https://github.com/cjohnhanson/tundish
cd tundish
cargo build --release
./target/release/tundish --version
```

The binary is `target/release/tundish`. Put it on `PATH` to run the
commands below.

## Usage

```sh
tundish publish slack --key slack:C123 '{"text":"Review PR 42"}'
tundish subscribe inbox --as reviewer --queue slack --consume on-ack
tundish pull inbox --as reviewer
```

In a new database, the publish prints `1` and the subscribe prints:

```text
created inbox
bound reviewer to inbox
rules: {"queue":"slack","select":"since_last_read","consume":"on_ack","share":"all","lease":600,"max_attempts":3,"start":"all"}
```

The pull prints:

```text
tundish: subscription=inbox subscriber=reviewer delivered=1 more=0 unacked=0 parked=0 errors=0 dropped=0 lease=0
[slack#1] slack:C123 {"text":"Review PR 42"}
```

To take responsibility for the item, run
`tundish ack 1 --as reviewer --subscription inbox`.
Keep `reviewer` as a stable subscriber name across sessions.

## How it works

A subscription stores a queue name, filter, template, and delivery rules.
A position records delivery progress. By default, every subscriber
receives each matching item once. With `share one` and
`on-ack`, a pull leases the item to one subscriber until an ack or lease
expiry. Acks and leases belong to that subscription. Publishing and
pulling open the local SQLite file and exit when done; tundish runs no
daemon.

## Python

The `tundish` Python package also installs the command. It supports
CPython 3.10 and later:

```python
import tundish

item_id = tundish.publish("slack", {"text": "hi"}, key="slack:C123")
```

## Documentation

- [Getting started](docs/getting-started.md): publish, pull, ack, and receive an item through a hook
- [How to deliver tundish items through a gaff handler](docs/how-to-gaff.md): handler setup and delivery intervals
- [How to publish into tundish from a program](docs/how-to-publish.md): Python and Slack Socket Mode
- [CLI reference](docs/cli-reference.md): commands, rules, config, and exit codes
- [What is tundish?](docs/what-is-tundish.md): queues, subscriptions, delivery, and retention

Run `tundish docs` to read the same documentation from the binary.

## License

MIT.

