tegwick
4d915a2617
Some checks failed
tamq-ci / test (push) Failing after 36s
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02f34-ead4-7a60-85cd-d7f08e22fa0e
72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# tmux-amq
|
|
|
|
Tmux Agentic Message Queueing (`tamq`) is a local, durable message queue for
|
|
agent workers running in gita-registered repositories.
|
|
|
|
The initial implementation is being bootstrapped from the standalone queue and
|
|
CLI contract. It will provide tmux endpoint lifecycle, local SQLite history and
|
|
leases, direct `@repo:` routing, JSONL export/replay, and a Unix-socket attach
|
|
protocol for a later coordination-engine adapter.
|
|
|
|
## 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 bootstrap currently 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 while observing 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"
|
|
```
|
|
|
|
Retries remain safety-gated and capped at nine attempts. Use `--policy-profile`
|
|
to select a profile; `--orwell` enables explicitly unsafe local diagnostics.
|
|
|
|
The Unix socket service now supports structured `ping`, `register`, `send`, and
|
|
`history` operations. Endpoint registrations and messages are persisted in the
|
|
same local SQLite database; delivery remains delegated to the control-mode
|
|
adapter.
|