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
97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
# SCOPE
|
|
|
|
## One-liner
|
|
|
|
Local durable message queue and tmux endpoint runtime for coordinating agent workers across gita-registered repositories.
|
|
|
|
## Core Idea
|
|
|
|
Keep tmux topology, terminal input observation, and durable local message state
|
|
behind a small CLI and Unix-socket protocol that agents can use without owning
|
|
a distributed coordination service.
|
|
|
|
## In Scope
|
|
|
|
- Local SQLite message history, leases, endpoint registrations, delivery state,
|
|
acknowledgements, replay, export, and bounded purging.
|
|
- Managed tmux endpoint lifecycle, control-mode output/injection, and the
|
|
full-duplex `tamq tap` PTY broker.
|
|
- Exact `gita` repository validation and direct `@repo: message` routing.
|
|
- Unix-socket operations for local clients and a future coordination-engine
|
|
adapter.
|
|
- Policy profiles, safety-gated retries, local diagnostics, tests, packaging,
|
|
shell completion, and operator documentation.
|
|
|
|
## Out of Scope
|
|
|
|
- Owning goal planning, workflow scheduling, or cross-host coordination; those
|
|
belong to `coordination-engine` and its consumers.
|
|
- Acting as a network-accessible or multi-host message broker.
|
|
- Bypassing `gita` registration or injecting arbitrary pane input outside the
|
|
supported tap/control-mode boundaries.
|
|
- Owning tmux, Codex, State Hub, or adjacent repositories' lifecycle.
|
|
|
|
## Current State
|
|
|
|
Version `0.1.0` is a usable local alpha for development and controlled
|
|
single-host experiments. It is not yet a dependable unattended coordination
|
|
transport.
|
|
|
|
| Intent capability | State | Evidence and remaining gap |
|
|
| --- | --- | --- |
|
|
| Direct repository addressing | Implemented | Exact `gita` validation and `@repo:` parsing are covered by tests. |
|
|
| Durable, inspectable local queue | Implemented | SQLite history, leases, endpoint records, inspect/history, JSONL export/replay, acknowledgement, and purge are present. |
|
|
| Local socket service | Implemented | Peer-credential checks and structured ping/register/send/history/ack/endpoints/disconnect operations are tested. |
|
|
| Tmux endpoint lifecycle and delivery | Implemented for local alpha | Real isolated-tmux and installed-package tests prove exact repository windows, stable reuse, control-mode injection, durable history transition, service stop, and bounded cleanup. |
|
|
| Full-duplex input observation | Implemented for local alpha | `tamq tap` uses raw outer-terminal mode, copies and propagates window dimensions, forwards lifecycle signals, preserves mouse/control bytes, and observes CR/LF address lines. A real tmux fixture covers geometry, resize, and raw mouse input. |
|
|
| Bounded retry behavior | Not enforced | Failed injection remains pending and becomes claimable after lease expiry, but no attempt counter or terminal failure state applies the configured cap. |
|
|
| Acknowledgement policy | Partially implemented | Explicit acknowledgement and the configuration field exist; delivery always marks a successful tmux injection as `injected`, irrespective of `delivery_ack_mode`. |
|
|
| Coordination-engine interoperability | Not implemented | The adapter contract and implementation remain in `TAMQ-WP-0002`. |
|
|
|
|
## Practical Usability
|
|
|
|
The installable alpha path was exercised successfully on 2026-08-24 with both
|
|
isolated fixtures and the operator's registered repositories. `make install`
|
|
produced a user-level `tamq` command; `tamq start --detach --command codex
|
|
railiance-platform activity-core` created two same-named live panes rooted at
|
|
their exact gita paths. Repeating the command retained the same session instance
|
|
and pane PIDs. The automated installed-package path also proved message
|
|
injection, history, status, service stop, and cleanup.
|
|
|
|
Suitable today:
|
|
|
|
- Local queue, history, export/replay, and diagnostic use.
|
|
- Interactive local Codex sessions over one or more gita-registered repositories.
|
|
- Controlled message-routing experiments between managed tmux endpoints.
|
|
- Developing and testing the future coordination-engine adapter against the
|
|
local socket boundary.
|
|
|
|
Not yet suitable:
|
|
|
|
- Unattended or high-confidence delivery where bounded retries and positive
|
|
recipient acknowledgement are required.
|
|
- Production-style operation without longer-running crash/terminal soak tests
|
|
and stronger process-supervision evidence.
|
|
- Cross-host messaging or use as a general-purpose broker.
|
|
|
|
The suite currently has 69 passing tests and 72% statement coverage. Coverage
|
|
is strongest in durable storage and registry handling, and weakest in the PTY
|
|
tap and CLI orchestration; PTY statement coverage increased from 23% to 33%,
|
|
while subprocess behavior is primarily proven by the real-tmux test. The
|
|
Forgejo CI job installs tmux and uv, runs the real-tmux and isolated
|
|
installed-package session tests with a deterministic gita fixture, and retains
|
|
CLI help/version smoke checks on Python 3.11.
|
|
|
|
## Next Usability Gates
|
|
|
|
- `TAMQ-WP-0003-T01` and `T02` still own bounded retry state and acknowledgement
|
|
enforcement. Its real tmux/PTY lifecycle gate (`T03`) is complete.
|
|
- `TAMQ-WP-0002` owns the coordination-engine adapter after the local delivery
|
|
contract is sufficiently reliable.
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: INTENT.md
|
|
- Agent instructions: AGENTS.md
|
|
- Workplans: workplans/
|
|
- Developer workflow: `uv sync --extra dev`, `make test`, and `make check`
|