tegwick
68475922bb
Some checks failed
tamq-ci / test (push) Failing after 6s
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc
139 lines
4.9 KiB
Markdown
139 lines
4.9 KiB
Markdown
# tmux-amq
|
|
|
|
Tmux Agentic Message Queueing (`tamq`) is a local, durable message queue for
|
|
agent workers running in gita-registered repositories.
|
|
|
|
The local alpha provides tmux endpoint lifecycle, local SQLite history and
|
|
leases, direct `@repo:` routing, JSONL export/replay, and a Unix-socket protocol
|
|
for a later coordination-engine adapter.
|
|
|
|
## Install and start a local session
|
|
|
|
Prerequisites must be available on `PATH`: Python 3.11+, [uv](https://docs.astral.sh/uv/),
|
|
tmux, gita, and the agent command you want to run (`codex` by default). Each
|
|
repository must already have an exact gita slug and path.
|
|
|
|
Install or upgrade `tamq` as an isolated user tool:
|
|
|
|
```bash
|
|
make install
|
|
command -v tamq
|
|
tamq --version
|
|
```
|
|
|
|
Start an attached two-repository Codex session:
|
|
|
|
```bash
|
|
tamq start --command codex railiance-platform activity-core
|
|
```
|
|
|
|
This creates or reuses the managed `tamq` session, opens same-named windows in
|
|
the exact gita paths for `railiance-platform` and `activity-core`, launches Codex
|
|
behind `tamq tap` in each new window, and attaches to the first window. Codex is
|
|
the default, so this is equivalent:
|
|
|
|
```bash
|
|
tamq start railiance-platform activity-core
|
|
```
|
|
|
|
Set up the session without attaching, then attach later:
|
|
|
|
```bash
|
|
tamq start --detach --command codex railiance-platform activity-core
|
|
tamq status
|
|
tamq attach
|
|
```
|
|
|
|
Repeated starts reuse existing windows and do not launch a second agent in
|
|
them. `--cmd` remains an alias for `--command`. A quoted command may include
|
|
arguments, for example `--command 'codex --profile local'`.
|
|
|
|
An already-running pane keeps the `tamq tap` code that launched it. After
|
|
upgrading from an earlier alpha, recreate the managed session once so terminal
|
|
mode and resize fixes take effect:
|
|
|
|
```bash
|
|
tamq stop
|
|
tmux kill-session -t tamq
|
|
tamq start --command codex railiance-platform activity-core
|
|
```
|
|
|
|
For degraded tmux-only use, `tamq start --no-service ...` launches the selected
|
|
agent directly, without `tamq tap`, socket endpoint registration, or message
|
|
delivery. Stop the broker and remove the managed tmux session explicitly when
|
|
finished:
|
|
|
|
```bash
|
|
tamq stop
|
|
tmux kill-session -t tamq
|
|
```
|
|
|
|
Uninstall the user tool from the checkout with `make uninstall`, or from
|
|
anywhere with `uv tool uninstall tmux-amq`.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
uv run pytest
|
|
uv run tamq --help
|
|
uv run tamq --version
|
|
uv run tamq start --cmd codex net-kingdom railiance-platform
|
|
uv run tamq attach
|
|
```
|
|
|
|
The alpha includes the local SQLite queue and a tmux endpoint
|
|
manager, strict gita target validation, and a control-mode client for tmux
|
|
operations/injection, and the PTY tap for full-duplex input observation. The
|
|
control-mode client alone does not expose arbitrary pane input; `tamq tap` is
|
|
the supported input-broker hook. `tamq send` remains available as an explicit
|
|
fallback. coordination-engine integration remains a later phase.
|
|
|
|
## Terminal architecture
|
|
|
|
`tamq` separates terminal coordination into three layers:
|
|
|
|
1. tmux control mode is the topology and output/control stream;
|
|
2. the local broker assigns endpoint/source identity and durably queues intent;
|
|
3. `tamq tap` is a full-duplex PTY proxy around the agent process. It forwards
|
|
bytes unchanged in raw terminal mode, propagates terminal resize and lifecycle
|
|
signals, and observes complete input lines for `@repo:` routing.
|
|
|
|
This keeps tmux-specific topology concerns separate from reusable terminal I/O
|
|
observation and message identity.
|
|
|
|
Pending messages are delivered through the control-mode client as
|
|
`#sender-repo: body`, then marked `injected` in SQLite. Delivery is
|
|
endpoint-scoped and uses the same message ID for retry/deduplication.
|
|
The visible endpoint label is `tmux-amq-<PID>`; each boot also receives an
|
|
instance nonce so PID reuse cannot collide with prior leases or receipts.
|
|
|
|
## Configuration
|
|
|
|
Configuration is read from `${XDG_CONFIG_HOME:-~/.config}/tamq/config.toml` (or
|
|
`$TAMQ_CONFIG`). Environment variables such as `TAMQ_SOCKET` and
|
|
`TAMQ_STATE_DIR` take precedence. The purge and startup advisory defaults can
|
|
be tuned without changing command lines:
|
|
|
|
```toml
|
|
[tamq]
|
|
state_dir = "/run/user/1000/tamq"
|
|
purge_before = "365d"
|
|
purge_max_size = "100MB"
|
|
history_max_size = "100MB"
|
|
delivery_poll_interval = "0.5"
|
|
|
|
[policy.profiles.diagnostics]
|
|
safety_gated_max_attempts = 2
|
|
delivery_ack_mode = "acknowledged"
|
|
```
|
|
|
|
Policy profiles accept a safety-gated retry cap of at most nine attempts, but
|
|
the alpha delivery path does not enforce attempt counting yet. Explicit
|
|
acknowledgement exists, while `delivery_ack_mode` enforcement and bounded retry
|
|
state are tracked in `TAMQ-WP-0003`. Use `--policy-profile` to select a profile;
|
|
`--orwell` enables explicitly unsafe local diagnostics.
|
|
|
|
The Unix socket service supports structured `ping`, `register`, `send`,
|
|
`history`, `ack`, `endpoints`, and `disconnect` operations. Endpoint
|
|
registrations and messages are persisted in the same local SQLite database;
|
|
delivery remains delegated to the control-mode adapter.
|