From 64dac56e37111c4d60f094bc90b35646a9bcfd29 Mon Sep 17 00:00:00 2001 From: nav Date: Wed, 1 Apr 2026 01:21:47 +0000 Subject: [PATCH] add Yonexus.Protocol submodule and update architecture docs --- .gitmodules | 3 + ARCHITECTURE.md | 178 ++++++++++++++++++++++++++++------------------- README.md | 85 ++++++++++++---------- Yonexus.Client | 2 +- Yonexus.Protocol | 1 + Yonexus.Server | 2 +- 6 files changed, 160 insertions(+), 111 deletions(-) create mode 160000 Yonexus.Protocol diff --git a/.gitmodules b/.gitmodules index e49052d..83c6705 100644 --- a/.gitmodules +++ b/.gitmodules @@ -4,3 +4,6 @@ [submodule "Yonexus.Client"] path = Yonexus.Client url = https://git.hangman-lab.top/nav/Yonexus.Client.git +[submodule "Yonexus.Protocol"] + path = Yonexus.Protocol + url = https://git.hangman-lab.top/nav/Yonexus.Protocol.git diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4b5d32b..18c7318 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -6,13 +6,13 @@ Yonexus is a cross-instance communication system for OpenClaw. The repository `Yonexus` is the **umbrella/specification repository** for the system. It contains: - high-level planning -- protocol specification -- shared architectural decisions +- architecture documents - references to implementation repositories as git submodules -Yonexus is implemented as two separate plugins: -- `Yonexus.Server` -- `Yonexus.Client` +Yonexus is implemented as three repositories: +- `Yonexus.Server` — central hub plugin +- `Yonexus.Client` — client plugin +- `Yonexus.Protocol` — shared protocol specification, referenced as a submodule by both --- @@ -23,20 +23,34 @@ Yonexus is implemented as two separate plugins: Purpose: - system-level planning - architecture documents -- protocol definition -- shared design decisions -- cross-repo coordination +- cross-cutting decisions that apply to both server and client +- coordination of sub-repositories via git submodules This repository should contain: - top-level planning docs -- protocol docs -- feature checklists - architecture overview -- cross-cutting decisions that apply to both server and client +- feature checklists +- cross-cutting design rationale -This repository should **not** become the place where all implementation code lives. +It references: +- `Yonexus.Server` (submodule) +- `Yonexus.Client` (submodule) +- `Yonexus.Protocol` (submodule) -## 2.2 `Yonexus.Server` +## 2.2 `Yonexus.Protocol` + +Purpose: +- protocol specification (PROTOCOL.md) +- canonical JSON shape references +- shared type definitions (planned) + +Referenced as a submodule by: +- `Yonexus.Server/protocol` +- `Yonexus.Client/protocol` + +This is the **single source of truth** for the Yonexus protocol. Both server and client implementations must conform to the protocol defined here. + +## 2.3 `Yonexus.Server` Purpose: - implementation of the central hub/server plugin @@ -44,7 +58,12 @@ Purpose: - server-side pairing/authentication/state tracking - server-side dispatch and routing behavior -## 2.3 `Yonexus.Client` +Contains: +- `protocol/` — submodule pointing to `Yonexus.Protocol` +- `PLAN.md` +- implementation code + +## 2.4 `Yonexus.Client` Purpose: - implementation of the client plugin @@ -53,9 +72,32 @@ Purpose: - client-side pairing confirmation and authenticated reconnect - client-side heartbeat and message sending +Contains: +- `protocol/` — submodule pointing to `Yonexus.Protocol` +- `PLAN.md` +- implementation code + --- -## 3. System Topology +## 3. Repository Graph + +``` +Yonexus (umbrella) +├── Yonexus.Protocol (submodule) +├── Yonexus.Server (submodule) +│ └── protocol/ (nested submodule -> Yonexus.Protocol) +└── Yonexus.Client (submodule) + └── protocol/ (nested submodule -> Yonexus.Protocol) +``` + +Policy: +- protocol changes are always committed to `Yonexus.Protocol` first +- `Yonexus.Server` and `Yonexus.Client` update their `protocol/` submodule ref after protocol version is stable +- umbrella `Yonexus` updates its submodule refs after server/client have stable versions + +--- + +## 4. System Topology A Yonexus deployment contains: - exactly one `Yonexus.Server` instance @@ -69,7 +111,7 @@ Topology assumptions: Visual model: -```text +``` Yonexus.Client A ---> \ Yonexus.Client B ----> Yonexus.Server @@ -79,29 +121,24 @@ Yonexus.Client C ---> --- -## 4. Shared vs Split Responsibilities +## 5. Shared vs Split Responsibilities -## 4.1 Shared System Concerns +## 5.1 Yonexus.Protocol — Shared -These belong to the umbrella repo and apply to both plugins: -- protocol format -- builtin message types +These belong to the protocol repo and apply to both plugins: +- protocol format and message categories +- builtin message types and their semantics - pairing security model - nonce/timestamp validation rules - heartbeat timing rules - message rewrite rules - reserved rule namespace (`builtin`) +- canonical JSON shapes - naming and terminology -These should live primarily in: -- `PLAN.md` -- `PROTOCOL.md` -- `FEAT.md` -- `ARCHITECTURE.md` +## 5.2 Server-Only Concerns (Yonexus.Server) -## 4.2 Server-Only Concerns - -These belong in `Yonexus.Server` planning/implementation: +These belong in `Yonexus.Server`: - WebSocket server startup - listen host/port config - client registry persistence @@ -113,9 +150,9 @@ These belong in `Yonexus.Server` planning/implementation: - client message rewriting and dispatch on server side - sending messages to connected clients -## 4.3 Client-Only Concerns +## 5.3 Client-Only Concerns (Yonexus.Client) -These belong in `Yonexus.Client` planning/implementation: +These belong in `Yonexus.Client`: - WebSocket client connection management - reconnect/backoff logic - local keypair generation @@ -128,16 +165,16 @@ These belong in `Yonexus.Client` planning/implementation: --- -## 5. Communication Model +## 6. Communication Model -## 5.1 Transport +## 6.1 Transport Transport is WebSocket. - `Yonexus.Server` acts as server - `Yonexus.Client` acts as client -## 5.2 Message Categories +## 6.2 Message Categories Two message categories exist on the same transport: @@ -175,9 +212,9 @@ ${rule_identifier}::${sender_identifier}::${message_content} --- -## 6. Security Architecture +## 7. Security Architecture -## 6.1 Pairing Model +## 7.1 Pairing Model Pairing is intentionally out-of-band. @@ -190,7 +227,7 @@ When a new client needs pairing: This preserves a basic human-mediated trust step. -## 6.2 Post-Pairing Authentication +## 7.2 Post-Pairing Authentication After pairing: - server issues a shared secret @@ -201,7 +238,7 @@ After pairing: - nonce - timestamp -## 6.3 Replay Protection +## 7.3 Replay Protection Server enforces: - timestamp freshness (`< 10s` drift) @@ -211,9 +248,9 @@ Server enforces: --- -## 7. State Ownership +## 8. State Ownership -## 7.1 Server-Owned State +## 8.1 Server-Owned State Canonical server-owned state includes: - allowed client identifiers @@ -226,7 +263,7 @@ Canonical server-owned state includes: - recent handshake attempt window - client liveness state -## 7.2 Client-Owned State +## 8.2 Client-Owned State Canonical client-owned state includes: - client identifier @@ -237,83 +274,78 @@ Canonical client-owned state includes: --- -## 8. Plugin API Boundaries +## 9. Plugin API Boundaries -## 8.1 Yonexus.Server API +## 9.1 Yonexus.Server API Planned public API: - `sendMessageToClient(identifier, message)` - `registerRule(rule, processor)` -## 8.2 Yonexus.Client API +## 9.2 Yonexus.Client API Planned public API: - `sendMessageToServer(message)` - `registerRule(rule, processor)` -The umbrella repo should define the semantics of these APIs, but implementation details belong in each submodule. +The protocol defines semantics; implementation details belong in each submodule. --- -## 9. Documentation Ownership +## 10. Documentation Ownership -## 9.1 Umbrella Repo Docs +## 10.1 Umbrella Repo Docs Should contain: - system architecture -- protocol spec - cross-cutting feature list - global design rationale +- cross-repo coordination notes -## 9.2 Server Repo Docs +## 10.2 Protocol Repo Docs + +Must contain: +- protocol specification (PROTOCOL.md) +- canonical message shapes +- protocol versioning notes + +## 10.3 Server Repo Docs Should contain: - server setup - server config reference - server persistence model - server operational behavior -- server implementation tasks +- implementation tasks -## 9.3 Client Repo Docs +## 10.4 Client Repo Docs Should contain: - client setup - client config reference - client local storage model - client reconnect/heartbeat behavior -- client implementation tasks +- implementation tasks --- -## 10. Development Flow +## 11. Development Flow Recommended flow: -1. define cross-cutting behavior in `Yonexus` -2. split actionable work into `Yonexus.Server` and `Yonexus.Client` -3. implement server-side protocol handling in `Yonexus.Server` -4. implement client-side protocol handling in `Yonexus.Client` -5. keep protocol changes synchronized back into umbrella docs - ---- - -## 11. Immediate Next Documents - -After this architecture file, the next documents to maintain are: -- `Yonexus.Server/PLAN.md` -- `Yonexus.Client/PLAN.md` -- optionally later: - - `Yonexus.Server/README.md` - - `Yonexus.Client/README.md` - - server/client task breakdown docs +1. define cross-cutting behavior in `Yonexus` umbrella +2. finalize protocol in `Yonexus.Protocol` +3. update submodule refs in `Yonexus.Server` and `Yonexus.Client` +4. implement server-side protocol handling in `Yonexus.Server` +5. implement client-side protocol handling in `Yonexus.Client` +6. keep protocol changes synchronized back into umbrella docs --- ## 12. Non-Goals of the Umbrella Repo The umbrella repo should avoid becoming: -- the only place where implementation changes happen -- a dumping ground for server-only details -- a dumping ground for client-only details +- the place where all implementation code lives +- a dumping ground for server-only or client-only details - a duplicate of submodule READMEs without system-level value Its job is coordination, not code concentration. diff --git a/README.md b/README.md index a5cc5fb..eada631 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ # Yonexus -Yonexus is a cross-instance communication system for OpenClaw built as **two separate plugins**: +Yonexus is a cross-instance communication system for OpenClaw built as **three separate repositories**: -- `Yonexus.Server` -- `Yonexus.Client` - -It is designed for scenarios where one OpenClaw instance acts as a central communication hub and multiple other OpenClaw instances connect to it as clients. +| Repository | Role | +|---|---| +| `Yonexus` | Umbrella — architecture, planning, and coordination | +| `Yonexus.Server` | Central hub plugin — accepts client connections, handles pairing/authentication | +| `Yonexus.Client` | Client plugin — connects to server, manages local identity | +| `Yonexus.Protocol` | Shared protocol specification — referenced as a submodule by both Server and Client | ## Overview @@ -33,6 +35,22 @@ Responsibilities: - send messages to server - receive messages from server via rule dispatch +### Yonexus.Protocol +Shared protocol specification repository. Both `Yonexus.Server` and `Yonexus.Client` reference this as a submodule at `protocol/`. + +--- + +## Repository Structure + +``` +Yonexus (umbrella) +├── Yonexus.Protocol ← shared protocol submodule +├── Yonexus.Server ← server plugin submodule +│ └── protocol/ ← points to Yonexus.Protocol +└── Yonexus.Client ← client plugin submodule + └── protocol/ ← points to Yonexus.Protocol +``` + --- ## Architecture @@ -67,48 +85,46 @@ After pairing: --- -## Current Spec Files - -This repository currently contains planning/spec-first documents: +## Current Repository Spec Files +### Umbrella (`Yonexus`) - `PLAN.md` — project plan and architecture -- `PROTOCOL.md` — builtin WebSocket protocol details +- `ARCHITECTURE.md` — architecture overview and repository graph - `FEAT.md` — implementation feature checklist ---- +### Protocol (`Yonexus.Protocol`) +- `PROTOCOL.md` — shared communication protocol specification -## Planned Plugin Manifests +### Server (`Yonexus.Server`) +- `PLAN.md` — server-specific implementation plan +- `protocol/` — submodule pointing to `Yonexus.Protocol` -This repo is expected to define separate plugin manifests for: - -- `plugin.server.json` -- `plugin.client.json` - -These represent the initial config surface for `Yonexus.Server` and `Yonexus.Client`. +### Client (`Yonexus.Client`) +- `PLAN.md` — client-specific implementation plan +- `protocol/` — submodule pointing to `Yonexus.Protocol` --- ## Planned TypeScript APIs ### Yonexus.Server -- `sendMessageToClient(identifier: string, message: string)` -- `registerRule(rule: string, processor: (message: string) => unknown)` +```ts +sendMessageToClient(identifier: string, message: string): Promise +registerRule(rule: string, processor: (message: string) => unknown): void +``` ### Yonexus.Client -- `sendMessageToServer(message: string)` -- `registerRule(rule: string, processor: (message: string) => unknown)` +```ts +sendMessageToServer(message: string): Promise +registerRule(rule: string, processor: (message: string) => unknown): void +``` Message format: - ```text ${rule_identifier}::${message_content} ``` -Reserved rule: - -```text -builtin -``` +Reserved rule: `builtin` --- @@ -140,19 +156,16 @@ builtin ## Status -Current repository status: - planning/specification stage - split-plugin architecture defined -- protocol draft defined +- protocol draft defined in `Yonexus.Protocol` - implementation not started yet --- -## Next Steps +## Repository URLs -Recommended next deliverables: -- plugin manifests -- source tree scaffolds for server/client -- protocol model types -- transport skeleton -- pairing/auth flow implementation +- [Yonexus (umbrella)](https://git.hangman-lab.top/nav/Yonexus) +- [Yonexus.Server](https://git.hangman-lab.top/nav/Yonexus.Server) +- [Yonexus.Client](https://git.hangman-lab.top/nav/Yonexus.Client) +- [Yonexus.Protocol](https://git.hangman-lab.top/nav/Yonexus.Protocol) diff --git a/Yonexus.Client b/Yonexus.Client index c5330bb..183f2ee 160000 --- a/Yonexus.Client +++ b/Yonexus.Client @@ -1 +1 @@ -Subproject commit c5330bb9f97cf77d625b561f62cff3500ea47fbd +Subproject commit 183f2eea6d15b801cc9e216ff911719f1f478bd5 diff --git a/Yonexus.Protocol b/Yonexus.Protocol new file mode 160000 index 0000000..9232aa7 --- /dev/null +++ b/Yonexus.Protocol @@ -0,0 +1 @@ +Subproject commit 9232aa7c1755adda6990a5a2f6c7c1a114285a73 diff --git a/Yonexus.Server b/Yonexus.Server index 23969af..871fe94 160000 --- a/Yonexus.Server +++ b/Yonexus.Server @@ -1 +1 @@ -Subproject commit 23969afa801b260eb97ee2888dfba6c023c69742 +Subproject commit 871fe94318cfc7056c7e64c6ca82c15da5a1a2c5