tegwick
e995cab1b8
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
154 lines
5.2 KiB
Markdown
154 lines
5.2 KiB
Markdown
---
|
|
id: TAMQ-WP-0006
|
|
type: workplan
|
|
title: "Shell-native message routing and explicit inbox filters"
|
|
domain: communication
|
|
repo: tmux-amq
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: coulomb-social
|
|
planning_priority: P0
|
|
planning_order: 11
|
|
created: "2026-08-24"
|
|
updated: "2026-08-24"
|
|
state_hub_workstream_id: "ea96613b-c9db-507e-bfa4-33bd046ef1bc"
|
|
---
|
|
|
|
# Shell-native message routing and explicit inbox filters
|
|
|
|
Make manual messaging usable from the ordinary shells that tamq opens. The
|
|
shell must recognize a repository address before trying to execute it, while
|
|
tamq remains neutral about shells, agents, and interactive programs.
|
|
|
|
## Required operator contract
|
|
|
|
Root help exposes the session shorthand and its explicit initial-command
|
|
option:
|
|
|
|
```bash
|
|
tamq --help
|
|
tamq --command codex flex-auth audit-core
|
|
```
|
|
|
|
Starting a session makes commands for its repository names available on each
|
|
new managed shell's `PATH`:
|
|
|
|
```bash
|
|
tamq flex-auth audit-core
|
|
@audit-core: Some message!
|
|
@flex-auth Another message
|
|
```
|
|
|
|
These are tamq-owned executable command shims, not shell aliases. They are
|
|
placed in the operator command directory that already exposes `tamq`, with an
|
|
explicit command-directory override and isolated fallback. They enqueue
|
|
messages and do nothing else by default. Reading a manual inbox produces
|
|
comment-safe text:
|
|
|
|
```text
|
|
#flex-auth: Some message! [m-...]
|
|
```
|
|
|
|
An operator may explicitly consume pending messages through a command:
|
|
|
|
```bash
|
|
tamq inbox --filter 'cat >> msg.log'
|
|
```
|
|
|
|
The filter receives one comment-safe message on standard input with message
|
|
metadata in environment variables. A zero exit acknowledges that message; a
|
|
failure leaves it pending and stops processing. No filter runs in the
|
|
background, modifies a pane, or becomes a startup default.
|
|
|
|
## Expose the session shorthand in root help
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "f6228d55-37f0-5be6-a868-f681f09d091b"
|
|
```
|
|
|
|
Document repository-first invocation and `--command COMMAND` in `tamq --help`,
|
|
including the terminal-neutral default and exact opt-in nature of the command.
|
|
|
|
Completed with a root-help shorthand section that names `--command COMMAND`,
|
|
the ordinary-shell default, and the absence of implicit terminal observation or
|
|
message injection.
|
|
|
|
## Install shell-native repository address commands
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "432e737c-b34e-56aa-8003-3f61e8ef4faf"
|
|
```
|
|
|
|
Populate the operator command directory that exposes `tamq` with safe `@repo`
|
|
and `@repo:` entry points for every requested repository; support an explicit
|
|
`TAMQ_COMMAND_DIR` and isolated state fallback, and also add the selected
|
|
directory to each newly created window's environment. Invocation must route
|
|
through tamq's existing validation and durable send path. Reject unsafe
|
|
repository names and refuse to overwrite commands not owned by tamq.
|
|
|
|
Completed with executable `@repo` and `@repo:` shims beside the installed tamq
|
|
command, `TAMQ_COMMAND_DIR` override and state fallback, tmux PATH propagation,
|
|
safe repository-name checks, tamq ownership markers, and collision refusal.
|
|
|
|
## Make manual inbox output comment-safe
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "b4ff430d-3b09-56de-9c1a-20afb018964c"
|
|
```
|
|
|
|
Render human-readable messages as shell comments prefixed with `#sender:` and
|
|
retain the message id for acknowledgement. Keep structured JSON stable for
|
|
automation.
|
|
|
|
Completed with `#sender:` rendering on every body line, durable ids on the
|
|
final line, and escaping of non-printing terminal control characters. JSON
|
|
output retains the original structured record.
|
|
|
|
## Add explicit pull-time inbox filters
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T04
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "d413ad83-06ff-5de1-97aa-256b4f684007"
|
|
```
|
|
|
|
Add `tamq inbox --filter COMMAND`. Invoke the command once per pending message,
|
|
pass only the comment-safe representation on standard input, expose bounded
|
|
metadata through environment variables, acknowledge only after a zero exit,
|
|
and leave failed and subsequent messages pending. Filters are explicit inbox
|
|
consumers and never background terminal interceptors.
|
|
|
|
Completed with sequential pull-time filters, bounded metadata environment,
|
|
comment-only standard input, success acknowledgement, fail-fast pending
|
|
retention, and rejection of ambiguous `--all`/`--json` combinations.
|
|
|
|
## Prove and document the ordinary-shell workflow
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T05
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "da957158-fb75-5232-9610-7684ebca45b5"
|
|
```
|
|
|
|
Cover root help, both address spellings, spaces and shell metacharacters in
|
|
message bodies, unknown targets, comment-safe inbox output, successful and
|
|
failed filters, acknowledgement behavior, path isolation, and installed tmux
|
|
acceptance. Update the operator quickstart and practical command reference.
|
|
|
|
Completed with 85 passing tests and 75% statement coverage. The isolated
|
|
installed-package test proves root help, real ordinary-shell command lookup
|
|
after shell startup, both neutral panes, durable delivery, comment-safe output,
|
|
filter acknowledgement, target-pane immutability, restart, recovery, and exact
|
|
explicit-command startup. A live user-install smoke repeated shell-native
|
|
routing with no target-pane change and left zero pending messages.
|