@dp-pcs/ogp 0.3.3 → 0.4.2

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

@@ -1,7 +1,7 @@
 ---
 skill_name: ogp-agent-comms
-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)
+version: 0.5.0
+description: Interactive wizard to configure agent-to-agent communication policies (updated for multi-framework `--for` workflows, 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
@@ -9,9 +9,11 @@ trigger: Use when the user wants to configure how their agent responds to incomi
 The OGP daemon must be installed. If you see errors like 'ogp: command not found', install it first:
 
 ```bash
-npm install -g github:dp-pcs/ogp --ignore-scripts
+npm install -g @dp-pcs/ogp
 ogp-install-skills
 ogp setup
+ogp agent-comms interview
+ogp config show
 ```
 
 Full documentation: https://github.com/dp-pcs/ogp
@@ -37,10 +39,22 @@ Agent-comms policies control HOW your agent responds to incoming messages (separ
 **Two layers:**
 1. **Scope grants** (doorman) - Controls which intents/topics are ALLOWED
 2. **Response policies** (this skill) - Controls HOW your agent RESPONDS
+3. **Human delivery preferences** - Controls WHERE and WHEN your agent surfaces federated requests back to the human
+
+**Important default:** when a federation request is approved, OGP auto-enables the `general` topic for that peer. Everything else still needs explicit policy if the user wants something more restrictive or more open.
 
 **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.
 
+**Human delivery behavior (v0.4.2+):**
+Use `humanDeliveryTarget` plus `inboundFederationPolicy.mode` to tell the agent whether it should forward everything, summarize, act autonomously, or wait for approval before replying.
+
+OGP now evaluates delegated-authority rules—global defaults, per-peer overrides, message-class-specific rules (`agent-work`, `human-relay`, `approval-request`, `status-update`), and topic overrides—before finalizing delivery behavior. This determines whether the agent may reply directly or must escalate to the configured human session. On OpenClaw, `/hooks/agent` is the preferred delivery path; it tries to request the actual human session key only when `hooks.allowRequestSessionKey=true` and the requested key matches configured prefixes. When the flag is false, the hook runs in the default session (`agent:main:main`), so Telegram sender identity continues to appear as injected/system/`cli`, which is the accepted `v0.4.2` limitation documented in the README and changelog. Lifecycle events such as federation approvals now surface through these same hook-driven turns, so humans see the lifecycle update without needing to poll another channel.
+
+On OpenClaw, human-facing federated work should be handled through the platform's hook-driven agent turn (`/hooks/agent`). Direct `sessions.send` injection is a lower-level fallback or sync mechanism, not the primary behavioral path.
+
+**Multi-Framework note:** Policies are framework-local. Use `ogp --for openclaw ...` for OpenClaw state and `ogp --for hermes ...` for Hermes state.
+
 ## Interactive Flow
 
 When invoked, guide the user through this flow:
@@ -49,35 +63,60 @@ When invoked, guide the user through this flow:
 
 ```bash
 # Verify OGP is running and has peers
-ogp status
-ogp federation list --status approved
+ogp config show
+ogp --for openclaw status
+ogp --for openclaw federation list --status approved
 ```
 
 If no approved peers, inform the user they need to federate first.
 
-### Step 2: Show Current Configuration
+### Step 2: Re-run the Delegated-Authority Interview First
+
+When the user is configuring overall human-delivery or autonomy behavior, start with the canonical interview command instead of approximating it manually:
+
+```bash
+ogp --for openclaw agent-comms interview
+```
+
+Use the Hermes variant when the active framework is Hermes:
+
+```bash
+ogp --for hermes agent-comms interview
+```
+
+This command updates:
+- `humanDeliveryTarget` when the framework supports it
+- `inboundFederationPolicy.mode`
+- delegated-authority defaults for human surfacing, relay handling, approval-required topics, and trusted-peer autonomy
+
+After the interview, continue with per-peer or per-topic policy commands only if the user wants something more specific.
+
+### Step 3: Show Current Configuration
 
 ```bash
 # Show current policies
-ogp agent-comms policies
+ogp --for openclaw agent-comms policies
 ```
 
-### Step 3: Ask What to Configure
+### Step 4: Ask What to Configure
 
 Present options:
 1. **Global defaults** - Apply to all peers (current and future)
 2. **Specific peer(s)** - Configure individual peers
 3. **View current policies** - Just show what's configured
 
-### Step 4: For Specific Peers - Multi-Select
+### Step 5: For Specific Peers - Multi-Select
 
 If configuring specific peers, show the list and allow multi-select:
 
+Use the peer list from:
+
 ```bash
-# List peers for selection
-ogp federation list --status approved --json
+ogp --for openclaw federation list --status approved
 ```
 
+Prefer the peer ID shown in the list. Some commands also accept a display-name match, but the peer ID is the safest input.
+
 Example interaction:
 ```
 Select peers to configure:
@@ -88,7 +127,7 @@ Select peers to configure:
 Selected: Stanislav, Alice
 ```
 
-### Step 5: Configure Topics
+### Step 6: Configure Topics
 
 Ask which topics the agent should engage on:
 
@@ -113,17 +152,18 @@ For each topic (or all topics), set the response level:
 | `summary` | High-level responses only, no specifics |
 | `escalate` | Ask human before responding |
 | `deny` | Politely decline to discuss |
+| `off` | Block the topic entirely |
 
 ### Step 7: Save Configuration
 
 ```bash
 # Save policies for selected peers
-ogp agent-comms configure <peer-id> \
+ogp --for openclaw agent-comms configure <peer-id> \
   --topics "memory-management,testing,general" \
   --level full
 
 # Or set global defaults
-ogp agent-comms configure --global \
+ogp --for openclaw agent-comms configure --global \
   --topics "general,testing" \
   --level summary
 ```
@@ -132,7 +172,7 @@ ogp agent-comms configure --global \
 
 ```bash
 # Show the updated configuration
-ogp agent-comms policies <peer-id>
+ogp --for openclaw agent-comms policies <peer-id>
 ```
 
 ## CLI Commands
@@ -140,7 +180,7 @@ ogp agent-comms policies <peer-id>
 ### View All Policies
 
 ```bash
-ogp agent-comms policies
+ogp --for openclaw agent-comms policies
 ```
 
 Shows global defaults and per-peer overrides.
@@ -148,7 +188,7 @@ Shows global defaults and per-peer overrides.
 ### View Peer Policy
 
 ```bash
-ogp agent-comms policies 302a300506032b65
+ogp --for openclaw agent-comms policies 302a300506032b65
 ```
 
 Shows effective policy for a specific peer (global + overrides).
@@ -156,7 +196,7 @@ Shows effective policy for a specific peer (global + overrides).
 ### Configure Global Defaults
 
 ```bash
-ogp agent-comms configure --global \
+ogp --for openclaw agent-comms configure --global \
   --topics "general,testing" \
   --level summary \
   --notes "Default: be helpful but don't overshare"
@@ -165,7 +205,7 @@ ogp agent-comms configure --global \
 ### Configure Specific Peer
 
 ```bash
-ogp agent-comms configure <peer-id> \
+ogp --for openclaw agent-comms configure <peer-id> \
   --topics "memory-management,testing,general" \
   --level full \
   --notes "Stan is a trusted collaborator"
@@ -174,29 +214,29 @@ ogp agent-comms configure <peer-id> \
 ### Configure Multiple Peers at Once
 
 ```bash
-ogp agent-comms configure stan,leonardo,alice \
+ogp --for openclaw agent-comms configure 302a300506032b65,5f8b2c,9d4e1f \
   --topics "testing" \
   --level full
 ```
 
-**Note:** Peers are referenced by their alias (the friendly name you assigned during federation), not their full peer ID.
+**Note:** Prefer peer IDs. Partial peer IDs or display-name matches may work, but peer IDs are canonical.
 
 ### Add Topic to Existing Policy
 
 ```bash
-ogp agent-comms add-topic <peer-id> calendar --level escalate
+ogp --for openclaw agent-comms add-topic <peer-id> calendar --level escalate
 ```
 
 ### Remove Topic
 
 ```bash
-ogp agent-comms remove-topic <peer-id> personal
+ogp --for openclaw agent-comms remove-topic <peer-id> personal
 ```
 
 ### Reset to Global Defaults
 
 ```bash
-ogp agent-comms reset <peer-id>
+ogp --for openclaw agent-comms reset <peer-id>
 ```
 
 ## Policy Inheritance
@@ -218,7 +258,7 @@ Effective for Stan:
 
 ## Response Policy Schema
 
-Stored in `~/.ogp/peers.json` under each peer:
+Stored in the active framework's `peers.json` under each peer:
 
 ```json
 {
@@ -240,12 +280,16 @@ Stored in `~/.ogp/peers.json` under each peer:
 }
 ```
 
-**Note:** The `alias` field (formerly `petname`) is the user-friendly name for the peer.
+**Note:** The `alias` field (formerly `petname`) is stored with the peer, but agent-comms commands should still prefer the peer ID shown by `ogp federation list`.
 
-Global defaults in `~/.ogp/config.json`:
+Global defaults live in the active framework config, for example `~/.ogp/config.json` or `~/.ogp-hermes/config.json`:
 
 ```json
 {
+  "humanDeliveryTarget": "telegram:123456789",
+  "inboundFederationPolicy": {
+    "mode": "summarize"
+  },
   "agentComms": {
     "globalPolicy": {
       "general": { "level": "summary" },
@@ -266,7 +310,7 @@ Global defaults in `~/.ogp/config.json`:
 When an agent-comms message arrives:
 
 1. **Doorman** checks if the intent/topic is allowed (scope grants)
-2. **Your agent** receives the message via notification
+2. **Your agent** receives the message via the local platform backend
 3. **Your agent** looks up the response policy:
    - Check peer-specific policy for this topic
    - Fall back to global policy for this topic
@@ -277,21 +321,25 @@ 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"
 
+**OpenClaw delivery path:** OGP should hand human-facing federated work to OpenClaw through `/hooks/agent`, letting the agent run a real turn and deliver via the configured human channel. A compact `sessions.send` note may still be used to keep session state synchronized, but that is secondary.
+
 **Multi-Agent Routing:** When `notifyTargets` is configured, messages are routed to the appropriate agent who then applies their own policies.
 
+**Human Delivery:** When `humanDeliveryTarget` is configured, the agent should treat "tell my human X" as a delivery obligation to that configured channel, not merely as something to mention in whatever session happens to be active.
+
 ## Activity Logging
 
 When enabled, all agent-comms interactions are logged:
 
 ```bash
 # View activity log
-ogp agent-comms activity
+ogp --for openclaw agent-comms activity
 
 # View for specific peer
-ogp agent-comms activity <peer-id>
+ogp --for openclaw agent-comms activity <peer-id>
 
 # View last N entries
-ogp agent-comms activity --last 20
+ogp --for openclaw agent-comms activity --last 20
 ```
 
 Log format:
@@ -307,7 +355,7 @@ Log format:
 ### Trusted Collaborator (Full Access)
 
 ```bash
-ogp agent-comms configure 302a300506032b65 \
+ogp --for openclaw agent-comms configure 302a300506032b65 \
   --topics "memory-management,testing,general,code-review" \
   --level full \
   --notes "Trusted peer, full collaboration"
@@ -316,7 +364,7 @@ ogp agent-comms configure 302a300506032b65 \
 ### Business Contact (Limited)
 
 ```bash
-ogp agent-comms configure 5f8b2c... \
+ogp --for openclaw agent-comms configure 5f8b2c... \
   --topics "general,status-updates" \
   --level summary \
   --notes "Professional contact, keep it high-level"
@@ -325,12 +373,28 @@ ogp agent-comms configure 5f8b2c... \
 ### New Federation (Cautious)
 
 ```bash
-ogp agent-comms configure --global \
+ogp --for openclaw agent-comms configure --global \
   --topics "general,testing" \
   --level escalate \
   --notes "Default: check with human for new peers"
 ```
 
+### Human Delivery Modes
+
+These now have a first-class CLI interview via `ogp agent-comms interview`, and they remain part of the same operational policy:
+
+- `forward` — forward all inbound federated requests/replies to the human
+- `summarize` — summarize and escalate only important/actionable items
+- `autonomous` — act independently unless blocked or explicitly told to relay something
+- `approval-required` — do not act or reply until the human approves
+
+Make the user's intent explicit during setup and documentation. Examples:
+
+- "Tell me everything that comes in from peers."
+- "Summarize most things, but escalate if you need me."
+- "Act on your own unless you are blocked."
+- "Never reply to a peer without clearing it with me first."
+
 ### Multi-Agent Setup
 
 With `notifyTargets` configured in `~/.ogp/config.json`:
@@ -352,29 +416,31 @@ Each agent can have independent policies. The main agent might have full access
 
 1. Verify the policy is saved:
    ```bash
-   ogp agent-comms policies <peer-id>
+   ogp --for openclaw agent-comms policies <peer-id>
    ```
 
 2. Check if the topic is in scope grants (doorman):
    ```bash
-   ogp federation scopes <peer-id>
+   ogp --for openclaw federation scopes <peer-id>
    ```
 
 3. Restart daemon to reload config:
    ```bash
-   ogp stop && ogp start
+   ogp --for openclaw stop && ogp --for openclaw start --background
    ```
 
 ### Policy not taking effect for new peer
 
 New peers inherit global defaults. Configure them specifically:
 ```bash
-ogp agent-comms configure 302a300506032b65 --topics "..." --level "..."
+ogp --for openclaw 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
+1. Check `notifyTargets` and `humanDeliveryTarget` in the active framework config
+2. Verify the target format: `telegram:chat_id` or a raw session key like `agent:main:telegram:direct:<chat-id>`
+3. For OpenClaw, verify hooks are enabled and the hook token is present
+4. For OpenClaw Gateway RPC debugging, use `wss://localhost:18789` against a TLS-enabled local gateway, not `ws://`
+5. Remember that a successful direct session injection is not the same thing as the agent correctly handling a human-delivery obligation

package/skills/ogp-expose/SKILL.md

@@ -1,7 +1,7 @@
 ---
 skill_name: ogp-expose
-version: 0.2.1
-description: Expose OGP daemon via public tunnel (cloudflared/ngrok). Automates tunnel setup so federated peers can reach your gateway from anywhere on the internet, without exposing your real IP address.
+version: 0.3.0
+description: Expose OGP via a public HTTPS endpoint, usually a stable Cloudflare hostname or named tunnel. Use when the user wants to verify or fix gateway reachability, align `gatewayUrl` with the real public endpoint, or set up temporary cloudflared/ngrok exposure for testing.
 trigger: Use when the user wants to expose their OGP daemon to the internet, get a public URL for federation, or set up a tunnel for peer discovery.
 requires:
   bins:
@@ -10,9 +10,12 @@ requires:
     - cloudflared
     - ngrok
   state_paths:
+    - ~/.ogp-meta/config.json
     - ~/.ogp/config.json
+    - ~/.ogp-hermes/config.json
     - ~/.ogp/tunnel.pid
     - ~/.ogp/tunnel.log
+    - ~/.cloudflared/config.yml
   install: npm install -g @dp-pcs/ogp
   docs: https://github.com/dp-pcs/ogp
 ---
@@ -21,9 +24,10 @@ requires:
 
 **Tunnels are optional — and often more private than alternatives.**
 
-`ogp expose` uses cloudflared or ngrok to create a secure public URL for your OGP daemon. This is one approach, not the only approach. You can expose your gateway however you prefer:
+`ogp expose` can create a temporary public URL for your OGP daemon. This is one approach, not the only approach. You can expose your gateway however you prefer:
 
-- **Cloudflared/ngrok tunnel** (default) — your real IP is never exposed; traffic routes through the tunnel provider's infrastructure
+- **Named Cloudflare tunnel / stable HTTPS hostname** (preferred) — long-lived canonical URL for federation
+- **Cloudflared/ngrok temporary tunnel** — useful for ad hoc testing
 - **Reverse proxy** (nginx, Caddy, etc.) — if you have a server with a static IP
 - **VPN/Tailscale** — federate only with peers on the same network
 - **Any publicly reachable URL** — update `gatewayUrl` in `~/.ogp/config.json` manually
@@ -38,6 +42,7 @@ The OGP daemon must be installed. If you see errors like 'ogp: command not found
 npm install -g @dp-pcs/ogp
 ogp-install-skills
 ogp setup
+ogp config show
 ```
 
 Full documentation: https://github.com/dp-pcs/ogp
@@ -46,15 +51,50 @@ Full documentation: https://github.com/dp-pcs/ogp
 
 # OGP Expose - Public Tunnel Setup
 
-This skill helps expose the OGP daemon to the internet using cloudflared or ngrok tunnels.
+This skill helps expose the OGP daemon to the internet and, more importantly, confirm that the public discovery endpoint matches the intended framework identity.
 
 ## When to Use
 
 Use this skill when:
 - User wants to make their OGP daemon publicly accessible
 - User needs a public URL for federation
-- User wants to set up tunneling for OGP
+- User wants to set up or verify a stable Cloudflare route
 - User is testing OGP federation remotely
+- User suspects `gatewayUrl` or tunnel config is stale or mismatched
+
+## Framework Selection
+
+If multiple frameworks are enabled, choose the framework first:
+
+```bash
+ogp config show
+ogp --for openclaw status
+ogp --for hermes status
+```
+
+Use `--for <framework>` on all exposure and verification commands when the target is not obvious.
+
+## Recommended Production Baseline
+
+Prefer one stable HTTPS hostname per framework:
+
+- OpenClaw: `https://ogp.example.com`
+- Hermes: `https://hermes.example.com`
+
+Those hostnames should terminate at a named Cloudflare tunnel or equivalent reverse proxy and forward to the local daemon port for that framework.
+
+After any tunnel or routing change, verify all three values agree:
+
+1. Local daemon discovery card
+2. Public discovery card
+3. `gatewayUrl` in the framework config
+
+```bash
+curl -s http://127.0.0.1:18790/.well-known/ogp
+curl -s https://ogp.example.com/.well-known/ogp
+```
+
+The public key and `gatewayUrl` should match. If they do not, do not federate yet.
 
 ## Prerequisites
 
@@ -95,10 +135,10 @@ ngrok config add-authtoken <your-token>
 
 ## Usage
 
-### Expose with Cloudflared (Default)
+### Expose with Cloudflared (Temporary / Ad Hoc)
 
 ```bash
-ogp expose
+ogp --for openclaw expose
 ```
 
 This will:
@@ -108,14 +148,14 @@ This will:
 
 **Update your config:**
 ```bash
-# Edit ~/.ogp/config.json
-# Set "gatewayUrl" to the URL shown by cloudflared
+# Edit the correct framework config
+# Set "gatewayUrl" to the URL shown by cloudflared only if this temporary URL is the intended canonical endpoint
 ```
 
-### Expose with ngrok
+### Expose with ngrok (Fallback Only)
 
 ```bash
-ogp expose --method ngrok
+ogp --for openclaw expose --method ngrok
 ```
 
 This will:
@@ -131,7 +171,7 @@ This will:
 
 ## Complete Setup Workflow
 
-### First-time Setup
+### First-time or Temporary Setup
 
 1. **Run OGP setup:**
    ```bash
@@ -141,12 +181,12 @@ This will:
 
 2. **Start the daemon:**
    ```bash
-   ogp start
+   ogp --for openclaw start
    ```
 
 3. **In a new terminal, expose the daemon:**
    ```bash
-   ogp expose
+   ogp --for openclaw expose
    ```
 
 4. **Copy the public URL** shown by cloudflared/ngrok
@@ -160,7 +200,7 @@ This will:
 6. **Restart the daemon:**
    ```bash
    # Stop with Ctrl+C in the daemon terminal
-   ogp start
+   ogp --for openclaw start
    ```
 
 7. **Verify the setup:**
@@ -190,16 +230,32 @@ credentials-file: ~/.cloudflared/<tunnel-id>.json
 ingress:
   - hostname: ogp.yourdomain.com
     service: http://localhost:18790
+  - hostname: hermes.yourdomain.com
+    service: http://localhost:18793
   - service: http_status:404
 EOF
 
 # Run tunnel
-cloudflared tunnel run ogp-daemon
+cloudflared tunnel run sarcastek-backend
+```
+
+Then make sure each framework config uses its own canonical hostname:
+
+```json
+{
+  "gatewayUrl": "https://ogp.yourdomain.com"
+}
+```
+
+```json
+{
+  "gatewayUrl": "https://hermes.yourdomain.com"
+}
 ```
 
 ## Comparison: Cloudflared vs ngrok
 
-### Cloudflared
+### Cloudflared / Stable Hostname
 **Pros:**
 - Free, unlimited usage
 - No signup required for temporary tunnels
@@ -228,12 +284,19 @@ cloudflared tunnel run ogp-daemon
 ### Tunnel won't start
 - **Cloudflared not found:** Install cloudflared
 - **ngrok not found:** Install ngrok and configure auth token
-- **Port already in use:** Stop other services on port 18790
+- **Port already in use:** Verify the framework's daemon port and stop stale listeners
+
+### Public URL resolves but serves the wrong framework
+- Check `ogp config show`
+- Check the relevant framework config's `gatewayUrl`
+- Verify local discovery card on the framework port
+- Verify Cloudflare ingress routes the hostname to the expected local port
+- If you recently switched from a temporary tunnel, remove stale fields like old temporary `gateway.publicUrl` overrides and keep only the canonical `gatewayUrl`
 
 ### Can't access public URL
 - Check firewall settings
-- Verify daemon is running (`ogp status`)
-- Test locally first: `curl http://localhost:18790/.well-known/ogp`
+- Verify daemon is running (`ogp --for <framework> status`)
+- Test locally first: `curl http://localhost:<port>/.well-known/ogp`
 
 ### Tunnel disconnects frequently
 - Check internet connection