feat: complete reliable coordination adapter
Some checks failed
tamq-ci / test (push) Failing after 5s
Some checks failed
tamq-ci / test (push) Failing after 5s
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc
This commit is contained in:
parent
25113f463e
commit
6d2ccc7760
30 changed files with 2553 additions and 144 deletions
|
|
@ -4,11 +4,11 @@ type: workplan
|
|||
title: "Coordination-engine adapter boundary"
|
||||
domain: communication
|
||||
repo: tmux-amq
|
||||
status: active
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: coulomb-social
|
||||
created: "2026-08-24"
|
||||
updated: "2026-08-24"
|
||||
updated: "2026-08-26"
|
||||
state_hub_workstream_id: "48da5fa7-b7bf-5d13-8edc-b90f266e241c"
|
||||
---
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ workflow/orchestration policy in coordination-engine.
|
|||
|
||||
```task
|
||||
id: TAMQ-WP-0002-T01
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a222dab7-edea-58c6-9dab-d684eb65c412"
|
||||
```
|
||||
|
|
@ -31,11 +31,17 @@ Define request, response, identity, delivery, acknowledgement, retry, and
|
|||
failure semantics for a coordination-engine client. Resolve protocol-version
|
||||
negotiation and document which system owns each state transition.
|
||||
|
||||
The implemented contract is `spec/coordination-engine-adapter-v0.1.md`. It
|
||||
defines same-user socket authentication, major-version and capability
|
||||
negotiation, exact endpoint resolution, message/correlation identity,
|
||||
idempotency conflicts, bounded delivery states, ack timeouts, late
|
||||
acknowledgement, recovery, and the TAMQ/coordination ownership boundary.
|
||||
|
||||
## Implement the coordination-engine client adapter
|
||||
|
||||
```task
|
||||
id: TAMQ-WP-0002-T02
|
||||
status: wait
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "195db613-05a3-58d8-9e94-2db34920576f"
|
||||
```
|
||||
|
|
@ -43,11 +49,18 @@ state_hub_task_id: "195db613-05a3-58d8-9e94-2db34920576f"
|
|||
Implement the adapter against the stable socket contract without importing
|
||||
tmux/control-mode concerns into coordination-engine. This task waits for T01.
|
||||
|
||||
`tamq.client` provides a transport-only async client and
|
||||
`CoordinationEngineAdapter`. It opens a fresh socket connection per operation,
|
||||
resolves one live repository endpoint, maps the coordination lease ID to a
|
||||
durable idempotency key, preserves trigger correlation metadata, and exposes
|
||||
receipt, acknowledgement, and terminal retry operations. Protocol constants
|
||||
are separate from the service and terminal implementation.
|
||||
|
||||
## Prove interoperability and recovery
|
||||
|
||||
```task
|
||||
id: TAMQ-WP-0002-T03
|
||||
status: wait
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "23c7f6c7-be48-5b6c-b85c-ae05d82cc277"
|
||||
```
|
||||
|
|
@ -55,3 +68,18 @@ state_hub_task_id: "23c7f6c7-be48-5b6c-b85c-ae05d82cc277"
|
|||
Add end-to-end coverage for delivery, acknowledgement, reconnect, replay,
|
||||
deduplication, incompatible protocol versions, and endpoint disappearance.
|
||||
Update both repositories' operator documentation with the verified workflow.
|
||||
|
||||
Unix-socket integration tests cover negotiation, identical-wake deduplication,
|
||||
idempotency conflict, durable receipt recovery after service restart,
|
||||
incompatible protocol, and disappeared endpoints. Reliability tests cover
|
||||
delivery, explicit and late acknowledgement, same-ID ack-timeout redelivery,
|
||||
lease expiry, exhaustion, and retry reset. JSONL replay now uses deterministic
|
||||
idempotency while retaining normal gita validation. TAMQ documentation and the
|
||||
coordination-engine worker-service specification link the verified contract.
|
||||
|
||||
## Residuals
|
||||
|
||||
This workplan does not implement coordination-engine's trigger observer,
|
||||
coordination leases, actionability decisions, checkpoints, or State Hub
|
||||
projection. Those remain owned by `COORDINATION-WP-0003` and consume this
|
||||
adapter rather than expanding TAMQ's scope.
|
||||
|
|
|
|||
|
|
@ -4,11 +4,11 @@ type: workplan
|
|||
title: "Delivery reliability and practical integration evidence"
|
||||
domain: communication
|
||||
repo: tmux-amq
|
||||
status: active
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: coulomb-social
|
||||
created: "2026-08-24"
|
||||
updated: "2026-08-24"
|
||||
updated: "2026-08-26"
|
||||
state_hub_workstream_id: "7961275b-8f1f-5827-b9fc-46b3ac35fb73"
|
||||
---
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ stable coordination-engine dependency.
|
|||
|
||||
```task
|
||||
id: TAMQ-WP-0003-T01
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "52c43745-5c28-599e-b74c-0386d5b51e68"
|
||||
```
|
||||
|
|
@ -31,11 +31,18 @@ Persist attempt counts and failure reasons, apply the selected policy profile's
|
|||
retry cap, define lease-expiry behavior, and introduce an inspectable terminal
|
||||
failure state. Prove restart-safe behavior and avoid tight retry loops.
|
||||
|
||||
Completed with schema-v6 persistent attempt, deadline, and failure fields.
|
||||
Lease acquisition consumes an attempt; write failure or lease expiry releases
|
||||
ownership into configured bounded backoff. The selected endpoint policy caps
|
||||
attempts from one to nine, exhaustion becomes `failed`, and `tamq retry` is the
|
||||
explicit recovery action. Protocol events retain attempt, cap, reason, and
|
||||
retry timing without raw terminal output.
|
||||
|
||||
## Enforce acknowledgement semantics
|
||||
|
||||
```task
|
||||
id: TAMQ-WP-0003-T02
|
||||
status: wait
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "ff88d6c9-f4d7-52c7-9645-7c3a7a34ccb4"
|
||||
```
|
||||
|
|
@ -44,6 +51,13 @@ Make `delivery_ack_mode` control whether injection completes delivery or waits
|
|||
for explicit recipient acknowledgement. Specify timeout, redelivery, duplicate,
|
||||
and late-acknowledgement behavior. This task follows the state model from T01.
|
||||
|
||||
Completed for every automatic delivery mode. `injected` completes after a
|
||||
successful terminal write. `acknowledged` enters `awaiting_ack`, schedules
|
||||
same-message-ID redelivery after the configured deadline, records `ack_timeout`
|
||||
on retries and exhaustion, and accepts a late acknowledgement even after
|
||||
`failed`. The contract warns that redelivery can duplicate terminal
|
||||
presentation and never represents task completion.
|
||||
|
||||
## Add real tmux and PTY lifecycle coverage
|
||||
|
||||
```task
|
||||
|
|
@ -70,7 +84,7 @@ entirely as documented.
|
|||
|
||||
```task
|
||||
id: TAMQ-WP-0003-T04
|
||||
status: wait
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "44939829-a52e-582a-b06b-60337b36080e"
|
||||
```
|
||||
|
|
@ -78,3 +92,14 @@ state_hub_task_id: "44939829-a52e-582a-b06b-60337b36080e"
|
|||
Run the integration suite in Forgejo CI with explicit tmux and gita setup. Update
|
||||
README claims about retries, acknowledgement, prerequisites, and maturity from
|
||||
verified behavior. This task follows T01-T03.
|
||||
|
||||
Forgejo CI now runs `make check`, including generated-gita and isolated tmux
|
||||
installation fixtures, compile/diff checks, and CLI/capture help smokes on
|
||||
Python 3.11. README, SCOPE, configuration examples, and the agent introduction
|
||||
describe the implemented state machine and terminal-comprehension boundary.
|
||||
|
||||
## Residuals
|
||||
|
||||
Long-duration and arbitrary-terminal soak coverage remains a maturity gate in
|
||||
SCOPE rather than a missing part of this bounded reliability contract. The
|
||||
coordination runtime above TAMQ remains owned by coordination-engine.
|
||||
|
|
|
|||
86
workplans/TAMQ-WP-0016-structured-protocol-capture.md
Normal file
86
workplans/TAMQ-WP-0016-structured-protocol-capture.md
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
id: TAMQ-WP-0016
|
||||
type: workplan
|
||||
title: "Structured communication protocol capture"
|
||||
domain: communication
|
||||
repo: tmux-amq
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: structured-protocol-capture
|
||||
created: "2026-08-25"
|
||||
updated: "2026-08-25"
|
||||
---
|
||||
|
||||
# Structured communication protocol capture
|
||||
|
||||
Retain reviewable evidence of TAMQ exchanges so agent onboarding and protocol
|
||||
friction can be assessed without recording arbitrary terminal sessions.
|
||||
|
||||
## Define the evidence and privacy boundary
|
||||
|
||||
```task
|
||||
id: TAMQ-WP-0016-T01
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
Capture only TAMQ protocol facts: addressed messages, provenance, worker block
|
||||
boundaries, allowlisted commands, line-limit decisions, endpoint lifecycle, and
|
||||
delivery outcomes. Do not capture unrelated pane output or ordinary shell
|
||||
input. Retain a message body once at acceptance rather than duplicating it at
|
||||
each lifecycle event.
|
||||
|
||||
## Add an append-only protocol ledger
|
||||
|
||||
```task
|
||||
id: TAMQ-WP-0016-T02
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
Add structured protocol events to SQLite schema version 5. Make acceptance
|
||||
events atomic with message admission, represent existing message lifecycle
|
||||
history during migration, and retain stable message/endpoint/repository links
|
||||
for filtering.
|
||||
|
||||
## Instrument onboarding-sensitive transitions
|
||||
|
||||
```task
|
||||
id: TAMQ-WP-0016-T03
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
Record operator versus worker origin, worker block start and close reason,
|
||||
invalid targets, limit blocks, operator-only command results, delivery mode,
|
||||
attempt, success, and failure class. Never store unrecognized command text or
|
||||
raw terminal output in event details.
|
||||
|
||||
## Provide a review and analysis path
|
||||
|
||||
```task
|
||||
id: TAMQ-WP-0016-T04
|
||||
status: done
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Add `tamq capture` with repository, endpoint, message, event-type, and bounded
|
||||
event-count filters. Render a summarized Markdown review by default and stable
|
||||
JSONL for analysis. Document the workflow and retention/privacy boundary in the
|
||||
agent introduction, README, CLI help, and scope assessment.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Schema migration backfills existing acceptance/display/injection/ack events
|
||||
without duplicating newly captured events on later opens.
|
||||
- Focused store, broker, service, renderer, and CLI tests cover atomic capture,
|
||||
worker termination evidence, provenance, failure classes, filtering, and
|
||||
Markdown/JSONL output.
|
||||
- `make check` passes the complete suite.
|
||||
|
||||
## Residuals
|
||||
|
||||
The capture deliberately describes transport behavior, not recipient
|
||||
comprehension or authorization. Long-term event retention and automated
|
||||
protocol-quality recommendations can be added after real captures show which
|
||||
summaries are useful.
|
||||
Loading…
Add table
Add a link
Reference in a new issue