agentmux 0.5.0

Multi-agent coordination runtime with inter-agent messaging across CLI, MCP, tmux, and ACP.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# MCP Surface

This module implements the MCP stdio server for `agentmux`.

## Responsibilities

- Advertise and handle MCP tools:
  - `list` (MVP requires `command="sessions"`)
  - `help`
  - `look`
  - `grant` (requires `command="list"` or `command="resolve"`)
  - `raww`
  - `send`
- Preserve canonical relay `look` success payloads without adapter reshaping:
  - tmux: `snapshot_format="lines"` + `snapshot_lines`
  - ACP: `snapshot_format="acp_entries_v1"` + `snapshot_entries` (+ freshness fields)
- Validate MCP request payloads.
- Forward valid requests to relay over the bundle Unix socket.
- Preserve relay error taxonomy/details when relay returns structured errors.
- Emit MCP inscriptions for request, success, and error events.

## Data Flow

1. MCP client calls `list`, `look`, `grant`, `raww`, or `send`.
2. MCP client can call `help` to discover tool/command schemas.
3. `src/mcp/mod.rs` validates parameter shape and transport-compatible options.
4. Request is forwarded as relay contract:
   - `list` (`command="sessions"`) -> one-shot `request_relay` probes (`RelayRequest::List`)
   - `look` -> `RelayStreamSession` (`RelayRequest::Look`)
   - `grant` (`command="list"`) -> one-shot `request_relay` probe
     (`RelayRequest::PermissionList`)
   - `grant` (`command="resolve"`) -> one-shot `request_relay` probe
     (`RelayRequest::PermissionResolve`)
   - `raww` -> `RelayStreamSession` (`RelayRequest::Raww`)
   - `send` -> `RelayStreamSession` (`RelayRequest::Chat`)
5. For `all=true`, MCP performs adapter fanout across bundle relays in
   deterministic lexicographic order.
6. Relay response is mapped back to MCP JSON payload.

## Permission Granting

- The `grant` tool exposes the relay ACP permission queue:
  - `command="list"` polls the bundle-scoped pending-request set; the response
    payload mirrors the `permission.requested` event fields exactly.
  - `command="resolve"` submits a decision (`outcome="selected"` requires
    `option_id`; `outcome="cancelled"` rejects `option_id`).
- MCP rejects decider-identity fields (`decided_by`, `ui_session_id`,
  `operator_session_id`) before relay submission; the deciding identity is
  association-derived and relay-stamped.
- Both subcommands are gated solely on the sender session's `grant` policy
  capability. The MCP server forwards the decision over its relay stream, and
  the relay authorizes it against the bundle policy preset. Sessions whose
  policy does not enable `grant` receive the relay submitter-gate rejection.

## Key Types

- `McpConfiguration`
  - startup configuration for runtime roots, bundle paths, and sender session
    identity.
- `McpServer`
  - tool router + handlers.
- `SendParams`
  - MCP `send` request schema, including optional transport-scoped timeout
    overrides (`quiescence_timeout_ms`, `acp_turn_timeout_ms`).

## Validation and Error Policy

- MCP rejects invalid request shapes before relay submission (for example empty
  targets or conflicting timeout fields).
- MCP does not perform shadow authorization checks.
- Relay `authorization_forbidden` and other relay codes are passed through as
  MCP errors with relay details.

## Event Handling Note

- Relay may return stream events alongside direct responses.
- Current MCP behavior logs these events via inscriptions and ignores them at
  tool-response level.