Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,11 @@ jobs:
for proto in \
macp/v1/envelope.proto \
macp/v1/core.proto \
macp/modes/decision/v1/decision.proto; do
macp/modes/decision/v1/decision.proto \
macp/modes/proposal/v1/proposal.proto \
macp/modes/task/v1/task.proto \
macp/modes/handoff/v1/handoff.proto \
macp/modes/quorum/v1/quorum.proto; do
if ! diff -q "$TMPDIR/$proto" "proto/$proto" > /dev/null 2>&1; then
echo "DRIFT: $proto"
diff -u "$TMPDIR/$proto" "proto/$proto" || true
Expand Down
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.PHONY: setup build test fmt clippy check sync-protos sync-protos-local check-protos

SPEC_PROTO_DIR := ../multiagentcoordinationprotocol/schemas/proto
PROTO_FILES := macp/v1/envelope.proto macp/v1/core.proto macp/modes/decision/v1/decision.proto
PROTO_FILES := macp/v1/envelope.proto macp/v1/core.proto macp/modes/decision/v1/decision.proto macp/modes/proposal/v1/proposal.proto macp/modes/task/v1/task.proto macp/modes/handoff/v1/handoff.proto macp/modes/quorum/v1/quorum.proto

## First-time setup: configure git hooks
setup:
Expand Down
37 changes: 33 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@ The MACP Runtime provides session-based message coordination between autonomous
- **RFC-0001 Compliant Protocol** — Structured protobuf schema with versioned envelope, typed errors, and capability negotiation
- **Initialize Handshake** — Protocol version negotiation and capability discovery before any session work begins
- **Pluggable Mode System** — Coordination logic is decoupled from runtime physics; ship new modes without touching the kernel
- **Decision Mode (RFC Lifecycle)** — Full Proposal → Evaluation → Objection → Vote → Commitment workflow with phase tracking and mode-aware authorization
- **Decision Mode** — Full Proposal → Evaluation → Objection → Vote → Commitment workflow with declared participant model and mode-aware authorization
- **Proposal Mode** — Lightweight propose/accept/reject lifecycle with peer participant model
- **Task Mode** — Orchestrated task assignment and completion tracking with structural-only determinism
- **Handoff Mode** — Delegated context transfer between agents with context-frozen semantics
- **Quorum Mode** — Threshold-based voting with quorum participant model and semantic-deterministic resolution
- **Multi-Round Convergence Mode (Experimental)** — Participant-based `all_equal` convergence strategy with automatic resolution (not advertised via discovery RPCs)
- **Session Cancellation** — Explicit `CancelSession` RPC to terminate sessions with a recorded reason
- **Message Deduplication** — Idempotent message handling via `seen_message_ids` tracking
Expand Down Expand Up @@ -39,6 +43,10 @@ cargo run
cargo run --bin client # basic decision mode demo
cargo run --bin fuzz_client # all error paths + multi-round + new RPCs
cargo run --bin multi_round_client # multi-round convergence demo
cargo run --bin proposal_client # proposal mode demo
cargo run --bin task_client # task mode demo
cargo run --bin handoff_client # handoff mode demo
cargo run --bin quorum_client # quorum mode demo
```

## Build & Development Commands
Expand Down Expand Up @@ -71,9 +79,21 @@ runtime/
│ │ ├── envelope.proto # Envelope, Ack, MACPError, SessionState
│ │ └── core.proto # Full service definition + all message types
│ └── modes/
│ └── decision/
│ ├── decision/
│ │ └── v1/
│ │ └── decision.proto # Decision mode payload types
│ ├── proposal/
│ │ └── v1/
│ │ └── proposal.proto # Proposal mode payload types
│ ├── task/
│ │ └── v1/
│ │ └── task.proto # Task mode payload types
│ ├── handoff/
│ │ └── v1/
│ │ └── handoff.proto # Handoff mode payload types
│ └── quorum/
│ └── v1/
│ └── decision.proto # Decision mode payload types
│ └── quorum.proto # Quorum mode payload types
├── src/
│ ├── main.rs # Entry point — wires Runtime + gRPC server
│ ├── lib.rs # Library root — proto modules + re-exports
Expand All @@ -85,12 +105,21 @@ runtime/
│ ├── runtime.rs # Runtime kernel (dispatch + apply ModeResponse)
│ ├── mode/
│ │ ├── mod.rs # Mode trait + ModeResponse enum
│ │ ├── util.rs # Shared mode utilities
│ │ ├── decision.rs # DecisionMode (RFC lifecycle)
│ │ ├── proposal.rs # ProposalMode (peer propose/accept/reject)
│ │ ├── task.rs # TaskMode (orchestrated task tracking)
│ │ ├── handoff.rs # HandoffMode (delegated context transfer)
│ │ ├── quorum.rs # QuorumMode (threshold-based voting)
│ │ └── multi_round.rs # MultiRoundMode (convergence)
│ └── bin/
│ ├── client.rs # Basic decision mode demo client
│ ├── fuzz_client.rs # Comprehensive error-path test client
│ └── multi_round_client.rs # Multi-round convergence demo client
│ ├── multi_round_client.rs # Multi-round convergence demo client
│ ├── proposal_client.rs # Proposal mode demo client
│ ├── task_client.rs # Task mode demo client
│ ├── handoff_client.rs # Handoff mode demo client
│ └── quorum_client.rs # Quorum mode demo client
├── build.rs # tonic-build proto compilation
├── Cargo.toml # Dependencies and project config
├── Makefile # Development shortcuts
Expand Down
4 changes: 4 additions & 0 deletions build.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
"macp/v1/envelope.proto",
"macp/v1/core.proto",
"macp/modes/decision/v1/decision.proto",
"macp/modes/proposal/v1/proposal.proto",
"macp/modes/task/v1/task.proto",
"macp/modes/handoff/v1/handoff.proto",
"macp/modes/quorum/v1/quorum.proto",
],
&["proto"],
)?;
Expand Down
18 changes: 13 additions & 5 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,12 +102,16 @@ Sessions follow a strict state machine with three states:

**Modes** are pluggable coordination strategies. The runtime provides the "physics" — session invariants, logging, TTL enforcement, routing — while modes provide the "coordination logic" — when to resolve, what state to track, and what convergence criteria to apply.

Two modes are built in:
Five standard modes are built in, plus one experimental mode:

| Mode Name | Aliases | Description |
|-----------|---------|-------------|
| `macp.mode.decision.v1` | `decision` | RFC-compliant decision lifecycle: Proposal → Evaluation → Objection → Vote → Commitment |
| `macp.mode.multi_round.v1` | `multi_round` | Participant-based convergence using `all_equal` strategy (experimental, not on discovery surfaces) |
| Mode Name | Aliases | Participant Model | Determinism | Description |
|-----------|---------|-------------------|-------------|-------------|
| `macp.mode.decision.v1` | `decision` | Declared | Semantic-deterministic | RFC-compliant decision lifecycle: Proposal → Evaluation → Objection → Vote → Commitment |
| `macp.mode.proposal.v1` | — | Peer | Semantic-deterministic | Lightweight propose/accept/reject lifecycle for peer-to-peer coordination |
| `macp.mode.task.v1` | — | Orchestrated | Structural-only | Task assignment and completion tracking with orchestrator-driven workflow |
| `macp.mode.handoff.v1` | — | Delegated | Context-frozen | Context transfer between agents with frozen context semantics |
| `macp.mode.quorum.v1` | — | Quorum | Semantic-deterministic | Threshold-based voting where resolution requires a configurable quorum |
| `macp.mode.multi_round.v1` | `multi_round` | Participant-based | Convergence | Participant-based convergence using `all_equal` strategy (experimental, not on discovery surfaces) |

An empty `mode` field defaults to `macp.mode.decision.v1` for backward compatibility.

Expand Down Expand Up @@ -166,6 +170,10 @@ This runtime consists of:
2. **Basic Client** (`client`) — a demo client exercising the happy path: Initialize, ListModes, SessionStart, Message, Resolve, GetSession.
3. **Fuzz Client** (`fuzz_client`) — a comprehensive test client exercising every error path, every new RPC, participant validation, signal messages, cancellation, and multi-round convergence.
4. **Multi-Round Client** (`multi_round_client`) — a focused demo of multi-round convergence with two participants reaching agreement.
5. **Proposal Client** (`proposal_client`) — a demo of the Proposal mode's peer-based propose/accept/reject workflow.
6. **Task Client** (`task_client`) — a demo of the Task mode's orchestrated assignment and completion tracking.
7. **Handoff Client** (`handoff_client`) — a demo of the Handoff mode's delegated context transfer between agents.
8. **Quorum Client** (`quorum_client`) — a demo of the Quorum mode's threshold-based voting and resolution.

---

Expand Down
Loading
Loading