From 3fc4d67cf176236877ae3f4b4865d700a4b73f89 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 26 Aug 2026 08:10:54 +0200 Subject: [PATCH] docs: align TAMQ worker adapter contract Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc --- README.md | 33 +++++++++++- spec/worker-coordination-service-v0.1.md | 69 ++++++++++++++---------- 2 files changed, 73 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index f84ca50..2130a7e 100644 --- a/README.md +++ b/README.md @@ -1 +1,32 @@ -Framework for digital coordination as goal-driven communication . \ No newline at end of file +# Coordination Engine + +Framework for digital coordination as goal-driven communication. + +## TAMQ worker-session adapter + +Coordination-engine owns trigger observation, actionability and safety policy, +coordination leases, checkpoints, and State Hub receipts. TAMQ separately owns +local repository sessions, durable messages, terminal delivery attempts, and +acknowledgement state. + +The implemented async boundary is provided by `tamq.client`: + +```python +from tamq.client import CoordinationEngineAdapter, WakeRequest + +receipt = await CoordinationEngineAdapter().wake( + WakeRequest( + lease_id="lease-123", + trigger_id="task-456:r7", + target_repo="audit-core", + prompt="Resume the actionable task and publish a checkpoint.", + ) +) +``` + +The coordination lease ID makes wake admission idempotent. An exact live TAMQ +endpoint is required; the adapter will not choose between multiple sessions or +start an agent implicitly. Transport states (`pending`, `awaiting_ack`, +`injected`, `acknowledged`, `failed`) are receipts, not workflow completion. +See `spec/worker-coordination-service-v0.1.md` and the canonical +`tmux-amq/spec/coordination-engine-adapter-v0.1.md` contract. diff --git a/spec/worker-coordination-service-v0.1.md b/spec/worker-coordination-service-v0.1.md index fe8474e..89f82f6 100644 --- a/spec/worker-coordination-service-v0.1.md +++ b/spec/worker-coordination-service-v0.1.md @@ -113,33 +113,33 @@ produces a stopped receipt for operator review. ## 5. Session wake contract The runtime integrates with `tmux-amq`, a separate local repository that owns -tmux session lifecycle, durable queueing, local leases, and PTY injection. -`tmux-amq` MUST remain functional when coordination-engine is unavailable. +tmux session lifecycle, durable queueing, delivery leases, acknowledgement +state, and PTY interaction. `tmux-amq` remains functional when +coordination-engine is unavailable. The implemented transport contract is +`tmux-amq/spec/coordination-engine-adapter-v0.1.md`; this section summarizes its +coordination-engine-facing obligations. + Only repositories registered in gita may be addressed. A session may be started -with, for example, -`tamq --cmd "codex" net-kingdom railiance-platform`; the bridge opens one -terminal per repository and runs the command. Messages addressed as -`@repo: text` are queued/injected into that repository's terminal as -`#sender-repo: text`. Coordination-engine calls the bridge through a local, -authenticated adapter; it does not manipulate tmux directly. +with, for example, `tamq --command codex --mode trigger net-kingdom +railiance-platform`; TAMQ opens one terminal per repository and runs the command +only because the operator selected it explicitly. Operator or worker messages +use `To:repo: text` and arrive in non-routable `From:sender[/o]: text` +envelopes. Coordination-engine calls TAMQ through the same-user Unix-socket +adapter and never manipulates tmux directly. Each tmux-amq endpoint is identified as `tmux-amq-`, where `` is the tmux server PID. Within one endpoint, a repository slug maps to exactly one tmux window; duplicate windows for the same repo are rejected or reconciled before attach. Different endpoint PIDs may independently host the same repo. -Outbound messages typed directly by an agent are detected through a tamq -tmux-control-mode client. The client intercepts input lines beginning with -`@:` and submits a structured local message using the -authenticated source window/repository. It does not wrap or replace the agent -process. Control-mode parsing MUST preserve ordinary input unchanged and must -not treat message-like text inside an unrelated multiline command as a message -unless the configured parser recognizes a complete address line. +Outbound messages are observed by TAMQ's explicit PTY broker. A worker +`To::` line begins a block that closes on an empty line, a new +address, or worker exit; operator input is one addressed line. TAMQ preserves +ordinary terminal bytes and records distinct worker/operator provenance. -If tmux control-mode interception is unavailable, tamq leaves ordinary terminal -use unchanged, marks interception unavailable in status/receipts, and does not -fall back to pane scraping or unverified injection. Operators may explicitly -use `tamq send @repo: message` as a degraded path. +If observation is unavailable, TAMQ leaves ordinary terminal use unchanged and +does not fall back to pane scraping. Operators may explicitly use +`tamq send 'To:repo: message'` as a degraded path. tmux-amq MUST retain a local message history sufficient to inspect delivery state and export it to a messages file. It MUST also support replaying a @@ -171,17 +171,30 @@ override these defaults. The CLI MUST provide tab completion through options, and known gita repository targets. Version 0.1 supports direct addressing only. Unknown or unregistered targets -are rejected; there is no broadcast or wildcard routing. If a target session is -absent, `tmux-amq` opens it and starts the configured command. The sender label -in the injected form is derived from the authenticated source repository, not -from message text. +are rejected; there is no broadcast or wildcard routing. Coordination-engine +resolves exactly one currently registered TAMQ endpoint for the target; zero is +unavailable and multiple matches require an explicit endpoint ID. It does not +implicitly create a session or choose a pane occupant. The sender label is +derived from the structured request or authenticated source window, not message +text. Delivery acknowledgment is configurable and defaults to `injected`, meaning the -message is considered delivered once tmux-amq successfully writes it to the -target PTY. An optional `acknowledged` mode retains the message until the target -agent explicitly confirms receipt; retries use the same message ID. This -facility carries coordination messages, not task/workplan state. Substantive -work, dependencies, and completion remain represented by State Hub facilities. +message is considered transport-delivered once TAMQ successfully writes it to +the target terminal. `acknowledged` enters `awaiting_ack` and redelivers the same +message ID after its deadline. Attempts, write failures, lease expiry, backoff, +and terminal `failed` state are durable and bounded by the selected profile. A +late acknowledgement wins; terminal retry is explicit. Duplicate terminal +presentation is possible and neither delivery mode proves agent comprehension +or task completion. + +Coordination-engine uses its coordination lease ID as TAMQ's idempotency key and +the trigger revision as correlation ID. Repeating an identical wake returns the +original TAMQ message ID; reusing the lease ID for a different request fails. +The client opens a new authenticated socket connection per operation, so +receipt recovery after broker restart uses `message` or `history` rather than a +connection session. If the bound endpoint disappears, repeating the identical +wake may rebind the same durable message ID to its one replacement endpoint; +TAMQ refuses implicit movement while the old endpoint remains live. Message bodies are human-readable UTF-8 plain text, limited to 8 KiB and preserving multiline content. The transport envelope carries structured IDs,