agentmux 0.4.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
79
80
81

# 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 require the MCP server's relay stream to hold
  `client_class ∈ {ui, operator}` plus the `grant` policy capability. The MCP
  server claims `operator` at startup only when
  `is_session_operator_class_authorized` confirms the sender session's bundle
  policy preset enables `operator-class`; otherwise it registers as `agent`
  and `grant` calls return 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 `delivery_mode` and 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.