@dp-pcs/ogp 0.2.27 → 0.2.30

package/docs/federation-flow.md

@@ -8,7 +8,8 @@ Detailed walkthrough of OGP federation message flows.
 2. [Federation Request](#federation-request)
 3. [Federation Approval](#federation-approval)
 4. [Message Exchange](#message-exchange)
-5. [Security Model](#security-model)
+5. [Federation Removal (Asymmetric Tear-Down)](#federation-removal-asymmetric-tear-down)
+6. [Security Model](#security-model)
 
 ## Discovery
 
@@ -30,6 +31,7 @@ Host: peer.example.com
   "email": "alice@example.com",
   "gatewayUrl": "https://peer.example.com",
   "publicKey": "302a300506032b6570032100abc123...",
+  "agentId": "main",
   "capabilities": {
     "intents": ["message", "task-request", "status-update", "agent-comms"],
     "features": ["scope-negotiation", "reply-callback", "project-intent"]
@@ -48,6 +50,7 @@ This endpoint:
 - Lists federation endpoints
 - Advertises gateway capabilities (v0.2.0+)
 - Indicates supported intents and features
+- Includes `agentId` (v0.2.28+) - identifies which OpenClaw agent owns this gateway
 
 ## Federation Request
 
@@ -64,7 +67,7 @@ ogp federation request https://bob.example.com
 Or specify a custom peer-id:
 
 ```bash
-ogp federation request https://bob.example.com peer-bob
+ogp federation request https://bob.example.com --alias bob
 ```
 
 This:
@@ -117,7 +120,7 @@ $ ogp federation list --status pending
 
 PENDING PEERS:
 
-  peer-alice
+  alice
     Name: Alice
     Status: pending
     Gateway: https://alice.example.com
@@ -133,7 +136,7 @@ Bob approves Alice's request. In v0.2.0+, Bob can include **scope grants** to co
 Approve with scope grants (v0.2.0+):
 
 ```bash
-ogp federation approve peer-alice \
+ogp federation approve alice \
   --intents message,agent-comms \
   --rate 100/3600 \
   --topics memory-management,task-delegation
@@ -142,7 +145,7 @@ ogp federation approve peer-alice \
 Or approve without restrictions (v0.1 compatibility):
 
 ```bash
-ogp federation approve peer-alice
+ogp federation approve alice
 ```
 
 This:
@@ -216,7 +219,7 @@ $ ogp federation list --status approved
 
 APPROVED PEERS:
 
-  peer-bob
+  bob
     Name: Bob
     Status: approved
     Gateway: https://bob.example.com
@@ -228,12 +231,12 @@ APPROVED PEERS:
 View detailed scopes:
 
 ```bash
-$ ogp federation scopes peer-bob
+$ ogp federation scopes bob
 
-Scopes granted TO peer-bob (what they can request from you):
+Scopes granted TO bob (what they can request from you):
   [not configured - full access]
 
-Scopes received FROM peer-bob (what you can request from them):
+Scopes received FROM bob (what you can request from them):
   • message (enabled)
     Rate limit: 100 requests / 3600 seconds
 
@@ -249,7 +252,7 @@ Alice sends a message to Bob.
 ### Alice Sends
 
 ```bash
-ogp federation send peer-bob message '{"text":"Hello, Bob!"}'
+ogp federation send bob message '{"text":"Hello, Bob!"}'
 ```
 
 This:
@@ -368,7 +371,7 @@ Agent-comms enables rich agent-to-agent communication with topic routing, priori
 ### Alice Sends Agent-Comms
 
 ```bash
-ogp federation agent peer-bob memory-management "How do you persist context?" --priority high --wait
+ogp federation agent bob memory-management "How do you persist context?" --priority high --wait
 ```
 
 ### Request
@@ -446,7 +449,7 @@ Project intents enable collaborative project management across federated peers.
 ### Alice Sends Contribution
 
 ```bash
-ogp project send-contribution peer-bob shared-app progress "Completed authentication system"
+ogp project send-contribution bob shared-app progress "Completed authentication system"
 ```
 
 ### Request
@@ -498,7 +501,7 @@ Bob sees:
 ### Alice Queries Bob's Project
 
 ```bash
-ogp project query-peer peer-bob shared-app --limit 10
+ogp project query-peer bob shared-app --limit 10
 ```
 
 ### Request
@@ -567,6 +570,118 @@ Content-Type: application/json
 
 Alice receives a unified view of project activity from both local and Bob's contributions.
 
+## Federation Removal (Asymmetric Tear-Down)
+
+Federation can be terminated by either peer at any time. OGP uses **asymmetric removal** — when one peer removes the other, the removed peer is notified but does not need to acknowledge the removal for it to take effect.
+
+### How Asymmetric Removal Works
+
+1. **Initiator removes peer** — Alice decides to remove Bob from her federation list
+2. **Notification sent (best-effort)** — Alice's daemon POSTs to Bob's `/federation/removed` endpoint
+3. **Removal takes effect immediately** — Alice's side is updated regardless of whether Bob receives the notification
+4. **Bob is notified (if reachable)** — If Bob's gateway is online, he receives the notification and updates his peer list
+
+**Important:** The removal notification is **best-effort only**. Network failures, firewalls, or offline peers do not prevent removal. The removing peer's decision is authoritative.
+
+### Alice Removes Bob
+
+```bash
+ogp federation remove bob
+```
+
+This:
+1. Signs a removal payload with Alice's private key
+2. POSTs the notification to Bob's `/federation/removed` endpoint
+3. Updates Bob's status to `removed` in Alice's `~/.ogp/peers.json`
+4. Notifies Alice's OpenClaw agent of the removal
+
+Alice sees:
+```
+✓ Notified peer of removal
+✓ Removed peer: bob (Bob)
+```
+
+If Bob is unreachable:
+```
+⚠ Could not notify peer of removal: fetch failed
+✓ Removed peer: bob (Bob)
+```
+
+The removal still succeeds — the warning only indicates Bob wasn't notified.
+
+### Removal Notification Payload
+
+Alice sends to Bob's `/federation/removed`:
+
+```http
+POST /federation/removed HTTP/1.1
+Host: bob.example.com
+Content-Type: application/json
+
+{
+  "peerId": "peer-alice",
+  "timestamp": "2026-04-02T04:10:00.000Z",
+  "signature": "a1b2c3d4e5f6..."
+}
+```
+
+The signature covers the JSON-serialized payload `{peerId, timestamp}` signed with Alice's Ed25519 private key.
+
+### Bob Receives Removal Notification
+
+Bob's OGP daemon:
+1. Validates required fields (`peerId`, `timestamp`, `signature`)
+2. Finds the peer by `peerId` (404 if unknown)
+3. Verifies the signature using Alice's public key (403 if invalid)
+4. Checks timestamp freshness (5-minute window, 400 if stale)
+5. Updates Alice's status to `removed` in `~/.ogp/peers.json`
+6. Notifies Bob's OpenClaw agent
+
+Bob sees:
+```
+[OGP Federation Removed] Alice (peer-alice) has removed your gateway from their federation
+Your gateway is no longer federated with Alice.
+You can re-establish federation by sending a new request if needed.
+```
+
+### Bob's Response to Alice
+
+```json
+{
+  "success": true,
+  "peerId": "peer-alice",
+  "status": "removed"
+}
+```
+
+Error responses:
+- `400` — Missing required fields or stale timestamp
+- `403` — Invalid signature (possible impersonation attempt)
+- `404` — Unknown peer (peer already removed or never existed)
+- `500` — Failed to update peer status
+
+### Re-establishing Federation
+
+After removal, either peer can re-establish federation by sending a new request:
+
+```bash
+# Alice wants to federate with Bob again
+ogp federation request https://bob.example.com
+
+# Or Bob initiates
+ogp federation request https://alice.example.com
+```
+
+The new request goes through the normal request → approval flow.
+
+### Removed Peer Status
+
+Peers with `removed` status remain in `~/.ogp/peers.json` for audit purposes but:
+- Cannot send messages to you
+- Do not appear in `ogp federation list` by default
+- Can be viewed with `ogp federation list --status removed` (flag not yet implemented)
+- Can be re-added by initiating a new federation request
+
 ## Security Model
 
 ### Keypair Generation

package/docs/quickstart.md

@@ -28,7 +28,19 @@ Run the interactive setup:
 ogp setup
 ```
 
-Answer the prompts:
+The wizard will auto-discover agents from your OpenClaw configuration and prompt you to select which agent owns this gateway:
+
+```
+=== OGP Setup ===
+
+Available agents:
+  1. 🦝 Junior (main)
+  2. ✍️ Scribe (scribe)
+
+Which agent owns this gateway? (number or ID) [1]:
+```
+
+Then answer the remaining prompts:
 
 ```
 Daemon port [18790]: <enter>
@@ -140,16 +152,16 @@ You should see:
 
 ## Step 7: Federate with a Peer
 
-Ask a friend to share their OGP gateway URL. The peer-id is now **optional** - OGP will auto-resolve it from the gateway's `/.well-known/ogp` endpoint:
+Ask a friend to share their OGP gateway URL. The alias is now **optional** - OGP will auto-resolve it from the gateway's `/.well-known/ogp` endpoint:
 
 ```bash
 ogp federation request https://peer.example.com
 ```
 
-Or specify a custom peer-id:
+Or specify a custom alias for easier reference:
 
 ```bash
-ogp federation request https://peer.example.com peer-bob
+ogp federation request https://peer.example.com --alias bob
 ```
 
 You'll see:
@@ -164,7 +176,7 @@ Wait for Bob to approve your request. In v0.2.3, Bob can approve with **scope gr
 
 ```bash
 # Bob approves with specific intents and rate limits
-ogp federation approve peer-alice \
+ogp federation approve alice \
   --intents message,agent-comms \
   --rate 100/3600 \
   --topics memory-management,task-delegation
@@ -173,7 +185,7 @@ ogp federation approve peer-alice \
 Or approve without restrictions (v0.1 compatibility):
 
 ```bash
-ogp federation approve peer-alice
+ogp federation approve alice
 ```
 
 Check your approved peers:
@@ -185,7 +197,7 @@ ogp federation list --status approved
 ## Step 8: Send Your First Message
 
 ```bash
-ogp federation send peer-bob message '{"text":"Hello from OGP!"}'
+ogp federation send bob message '{"text":"Hello from OGP!"}'
 ```
 
 Bob's OpenClaw agent will receive a notification via Telegram (if configured) or system event:
@@ -202,16 +214,16 @@ Use agent-comms for rich agent collaboration:
 
 ```bash
 # Send agent-comms with topic routing
-ogp federation agent peer-bob memory-management "How do you persist context?"
+ogp federation agent bob memory-management "How do you persist context?"
 
 # High-priority message
-ogp federation agent peer-bob task-delegation "Schedule standup ASAP" --priority high
+ogp federation agent bob task-delegation "Schedule standup ASAP" --priority high
 
 # Wait for reply
-ogp federation agent peer-bob queries "What's the status?" --wait --timeout 60000
+ogp federation agent bob queries "What's the status?" --wait --timeout 60000
 
 # Start a conversation thread
-ogp federation agent peer-bob project-planning "Let's discuss sprint goals" --conversation sprint-42
+ogp federation agent bob project-planning "Let's discuss sprint goals" --conversation sprint-42
 ```
 
 ### Configure Response Policies
@@ -226,10 +238,10 @@ ogp agent-comms policies
 ogp agent-comms configure --global --topics "general,testing" --level summary
 
 # Configure specific peer
-ogp agent-comms configure peer-bob --topics "memory-management" --level full
+ogp agent-comms configure bob --topics "memory-management" --level full
 
 # Add escalation for sensitive topics
-ogp agent-comms add-topic peer-bob calendar --level escalate
+ogp agent-comms add-topic bob calendar --level escalate
 ```
 
 Response levels:
@@ -258,10 +270,10 @@ ogp project status my-app
 ogp project query my-app --limit 10
 
 # Send contribution to peer's project
-ogp project send-contribution peer-bob shared-project progress "Deployed staging environment"
+ogp project send-contribution bob shared-project progress "Deployed staging environment"
 
 # Query peer's project contributions
-ogp project query-peer peer-bob shared-project
+ogp project query-peer bob shared-project
 ```
 
 ### Custom Intents
@@ -285,13 +297,13 @@ ogp intent remove deployment
 
 ```bash
 # Task request
-ogp federation send peer-bob task-request '{
+ogp federation send bob task-request '{
   "taskType": "analysis",
   "description": "Analyze server logs from last hour"
 }'
 
 # Status update
-ogp federation send peer-bob status-update '{
+ogp federation send bob status-update '{
   "status": "online",
   "message": "Ready to collaborate"
 }'
@@ -306,22 +318,22 @@ When someone sends you a federation request:
 ogp federation list --status pending
 
 # Approve with scope grants (v0.2.0+)
-ogp federation approve peer-charlie \
+ogp federation approve charlie \
   --intents message,agent-comms \
   --rate 50/3600 \
   --topics general,project-updates
 
 # Or approve without restrictions
-ogp federation approve peer-charlie
+ogp federation approve charlie
 
 # Or reject
-ogp federation reject peer-charlie
+ogp federation reject charlie
 
 # View granted scopes
-ogp federation scopes peer-charlie
+ogp federation scopes charlie
 
 # Update scopes later
-ogp federation grant peer-charlie \
+ogp federation grant charlie \
   --intents agent-comms \
   --topics memory-management,planning \
   --rate 100/3600
@@ -365,7 +377,7 @@ The peer must approve your federation request first. Contact them or check their
 Check the peer's granted scopes:
 
 ```bash
-ogp federation scopes peer-bob
+ogp federation scopes bob
 ```
 
 Request the peer to update your grants if needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-pcs/ogp",
-  "version": "0.2.27",
+  "version": "0.2.30",
   "description": "Open Gateway Protocol (OGP) - Peer-to-peer federation daemon for OpenClaw AI gateways with cryptographic signatures",
   "type": "module",
   "main": "./dist/index.js",

package/skills/ogp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 skill_name: ogp
-version: 2.2.0
+version: 2.2.1
 description: >
   OGP (Open Gateway Protocol) — federated agent communication, peer management,
   and project collaboration across OpenClaw gateways. Use when the user asks to
@@ -86,6 +86,79 @@ When enabled, your daemon auto-registers on startup and heartbeats every 30 seco
 
 ---
 
+## Configuration
+
+### Agent ID (v0.2.28+)
+
+The `agentId` field identifies which OpenClaw agent owns this OGP gateway. During `ogp setup`, the wizard auto-discovers available agents from your OpenClaw configuration:
+
+```
+Available agents:
+  1. 🦝 Junior (main)
+  2. ✍️ Scribe (scribe)
+  3. ⚡ Optimus (optimus)
+
+Which agent owns this gateway? (number or ID) [1]:
+```
+
+**Example config with agentId:**
+```json
+{
+  "daemonPort": 18790,
+  "openclawUrl": "http://localhost:18789",
+  "openclawToken": "your-token",
+  "gatewayUrl": "https://your-gateway.example.com",
+  "displayName": "Alice",
+  "email": "alice@example.com",
+  "stateDir": "~/.ogp",
+  "agentId": "main"
+}
+```
+
+### Notification Routing — notifyTargets (v0.2.28+)
+
+The `notifyTargets` field enables per-agent notification routing. When OGP sends notifications to your OpenClaw instance, it routes to specific agents based on the message context.
+
+**Configuration fields:**
+- **`notifyTarget`** (legacy, string): Single notification target for all messages. Maintained for backward compatibility.
+- **`notifyTargets`** (object): Map of agent names to notification targets. Example: `{"main": "telegram:...", "scribe": "telegram:..."}`
+
+**Example configuration with multiple agents:**
+
+```json
+{
+  "daemonPort": 18790,
+  "openclawUrl": "http://localhost:18789",
+  "openclawToken": "your-token",
+  "gatewayUrl": "https://your-gateway.example.com",
+  "displayName": "Alice",
+  "email": "alice@example.com",
+  "stateDir": "~/.ogp",
+  "agentId": "main",
+  "notifyTarget": "telegram:123456789",
+  "notifyTargets": {
+    "main": "telegram:123456789",
+    "scribe": "telegram:987654321",
+    "optimus": "telegram:555666777"
+  }
+}
+```
+
+**Resolution priority:**
+
+When routing notifications, OGP resolves the target in this order:
+
+1. **`notifyTargets[agent]`** — If the agent is specified and exists in `notifyTargets`, use that target
+2. **`notifyTarget`** — Fall back to the legacy single target for backward compatibility
+3. **Default** — If neither is set, the notification is sent without a specific target (OpenClaw routes to the default channel)
+
+This allows you to:
+- Route federation messages to different agents based on context
+- Maintain backward compatibility with existing single-agent setups
+- Gradually migrate to multi-agent routing without breaking existing configurations
+
+---
+
 ## Federation Management
 
 ### List all peers
@@ -97,9 +170,12 @@ ogp federation list --status approved
 
 ### Request federation with a new peer
 ```bash
-ogp federation request <peer-gateway-url> [peer-id]
-# Example:
-ogp federation request https://giving-produces-microphone-mild.trycloudflare.com stanislav
+ogp federation request <peer-gateway-url> [--alias <name>]
+# Example with alias:
+ogp federation request https://giving-produces-microphone-mild.trycloudflare.com --alias stanislav
+
+# Alias auto-resolves from gateway's display name if omitted:
+ogp federation request https://giving-produces-microphone-mild.trycloudflare.com
 ```
 
 ### Approve an inbound federation request
@@ -141,7 +217,7 @@ ogp federation send <peer-id> <intent> '<json-payload>'
 ```bash
 ogp federation agent <peer-id> <topic> "<message>"
 # Example:
-ogp federation agent giving-produces-microphone-mild.trycloudflare.com:18790 general "Hey, can you check on project synapse?"
+ogp federation agent stanislav general "Hey, can you check on project synapse?"
 ```
 
 ### Manage agent-comms policies (what topics you'll respond to)
@@ -271,7 +347,7 @@ ogp start --background
 
 | File | Purpose |
 |------|---------|
-| `~/.ogp/config.json` | Gateway config (URL, email, port) |
+| `~/.ogp/config.json` | Gateway config (URL, email, port, notifyTargets, agentId) |
 | `~/.ogp/keypair.json` | Ed25519 signing keypair |
 | `~/.ogp/peers.json` | All federation peers + scopes |
 | `~/.ogp/projects.json` | Local project data + contributions |
@@ -288,3 +364,4 @@ ogp start --background
 - **Project isolation:** Projects are scoped to their member list. Full mesh federation does NOT give all peers access to all projects. A peer only sees projects they are a member of.
 - **Signatures:** All federation messages are signed with Ed25519. Peer's public key is stored in `peers.json` at federation time.
 - **Rendezvous is optional:** Peers with a static IP or existing tunnel continue working unchanged. Rendezvous is an additional discovery path, not a requirement.
+- **Notification Routing:** The `notifyTargets` config enables multi-agent setups where different agents handle different types of federation messages.

package/skills/ogp-agent-comms/SKILL.md

@@ -1,7 +1,7 @@
 ---
 skill_name: ogp-agent-comms
-version: 0.2.1
-description: Interactive wizard to configure agent-to-agent communication policies (updated for OGP 0.2.24+ peer identity)
+version: 0.2.2
+description: Interactive wizard to configure agent-to-agent communication policies (updated for OGP 0.2.24+ peer identity and 0.2.28+ multi-agent routing)
 trigger: Use when the user wants to configure how their agent responds to incoming agent-comms messages from federated peers
 ---
 ## Prerequisites
@@ -38,6 +38,9 @@ Agent-comms policies control HOW your agent responds to incoming messages (separ
 1. **Scope grants** (doorman) - Controls which intents/topics are ALLOWED
 2. **Response policies** (this skill) - Controls HOW your agent RESPONDS
 
+**Multi-Agent Routing (v0.2.28+):**
+When using `notifyTargets` in your OGP config, federation messages can be routed to specific agents based on the message context. Each agent can have its own agent-comms policies.
+
 ## Interactive Flow
 
 When invoked, guide the user through this flow:
@@ -176,6 +179,8 @@ ogp agent-comms configure stan,leonardo,alice \
   --level full
 ```
 
+**Note:** Peers are referenced by their alias (the friendly name you assigned during federation), not their full peer ID.
+
 ### Add Topic to Existing Policy
 
 ```bash
@@ -218,7 +223,7 @@ Stored in `~/.ogp/peers.json` under each peer:
 ```json
 {
   "id": "302a300506032b65",
-  "displayName": "Stanislav",
+  "alias": "Stanislav",
   "responsePolicy": {
     "memory-management": {
       "level": "full",
@@ -235,6 +240,8 @@ Stored in `~/.ogp/peers.json` under each peer:
 }
 ```
 
+**Note:** The `alias` field (formerly `petname`) is the user-friendly name for the peer.
+
 Global defaults in `~/.ogp/config.json`:
 
 ```json
@@ -246,6 +253,10 @@ Global defaults in `~/.ogp/config.json`:
     },
     "defaultLevel": "summary",
     "activityLog": true
+  },
+  "notifyTargets": {
+    "main": "telegram:123456789",
+    "scribe": "telegram:987654321"
   }
 }
 ```
@@ -266,6 +277,8 @@ When an agent-comms message arrives:
    - `escalate`: "Let me check with my human and get back to you"
    - `deny`: "I'm not able to discuss that topic"
 
+**Multi-Agent Routing:** When `notifyTargets` is configured, messages are routed to the appropriate agent who then applies their own policies.
+
 ## Activity Logging
 
 When enabled, all agent-comms interactions are logged:
@@ -318,6 +331,21 @@ ogp agent-comms configure --global \
   --notes "Default: check with human for new peers"
 ```
 
+### Multi-Agent Setup
+
+With `notifyTargets` configured in `~/.ogp/config.json`:
+
+```json
+{
+  "notifyTargets": {
+    "main": "telegram:123456789",
+    "scribe": "telegram:987654321"
+  }
+}
+```
+
+Each agent can have independent policies. The main agent might have full access for operational topics, while the scribe agent handles content-related discussions.
+
 ## Troubleshooting
 
 ### Agent not following policies
@@ -343,3 +371,10 @@ New peers inherit global defaults. Configure them specifically:
 ```bash
 ogp agent-comms configure 302a300506032b65 --topics "..." --level "..."
 ```
+
+### Multi-Agent Routing Issues
+
+If notifications aren't reaching the right agent:
+1. Check `notifyTargets` in `~/.ogp/config.json`
+2. Verify the target format: `telegram:chat_id` or `session:session_id`
+3. Check OpenClaw hook configuration for proper routing

package/skills/ogp-project/SKILL.md

@@ -1,7 +1,7 @@
 ---
 skill_name: ogp-project
-version: 1.1.0
-description: Agent-aware project context skill for OGP with interview, freeform logging, and cross-peer summarization (updated for OGP 0.2.24+ peer identity)
+version: 1.1.1
+description: Agent-aware project context skill for OGP with interview, freeform logging, and cross-peer summarization (updated for OGP 0.2.24+ peer identity and 0.2.28+ multi-agent notifyTargets)
 trigger: Use when the user wants to create, manage, log to, or summarize OGP projects. This includes project context interviews, freeform activity logging, and cross-peer collaboration. Also triggers on natural logging phrases like "remember this for project X", "account for this", "make note of", "track this", "jot this down", "save this to", "document this" when a project context is active or named.
 requires:
   bins:
@@ -24,7 +24,9 @@ ogp setup
 ogp start
 ```
 
-**Note on Peer IDs (OGP 0.2.24+):** Peers are identified by the first 16 characters of their Ed25519 public key (e.g., `302a300506032b65`). This is stable even when their gateway URL changes.
+**Note on Peer IDs (OGP 0.2.24+):** Peers are identified by the first 16 characters of their Ed25519 public key (e.g., `302a300506032b65`). This is stable even when their gateway URL changes. You can also reference peers by their **alias** (the friendly name you assigned during federation).
+
+**Note on Multi-Agent Routing (OGP 0.2.28+):** When `notifyTargets` is configured in `~/.ogp/config.json`, project-related federation messages can be routed to specific agents. Each agent can have its own project context and policies.
 
 Full documentation: https://github.com/dp-pcs/ogp