89daa63db0
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
128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
---
|
|
id: TAMQ-WP-0006
|
|
type: workplan
|
|
title: "Shell-native message routing and explicit inbox filters"
|
|
domain: communication
|
|
repo: tmux-amq
|
|
status: active
|
|
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 per-session executable command shims, not shell aliases. 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: progress
|
|
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.
|
|
|
|
## Install shell-native repository address commands
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T02
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "432e737c-b34e-56aa-8003-3f61e8ef4faf"
|
|
```
|
|
|
|
Create a private command directory for the managed session, populate it with
|
|
safe `@repo` and `@repo:` entry points for every requested repository, and add
|
|
that directory to each newly created window's environment. Invocation must
|
|
route through tamq's existing validation and durable send path. Reject unsafe
|
|
repository names rather than creating ambiguous executable paths.
|
|
|
|
## Make manual inbox output comment-safe
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T03
|
|
status: todo
|
|
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.
|
|
|
|
## Add explicit pull-time inbox filters
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T04
|
|
status: todo
|
|
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.
|
|
|
|
## Prove and document the ordinary-shell workflow
|
|
|
|
```task
|
|
id: TAMQ-WP-0006-T05
|
|
status: todo
|
|
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.
|