@dp-pcs/ogp 0.3.2 → 0.4.2

package/docs/case-studies/crash_observations.md

@@ -0,0 +1,250 @@
+# OpenClaw Crash Observations - April 7, 2026
+
+> **Note:** This document is a sanitized version of internal debugging notes. API key fragments, file paths, and system-specific details have been removed or generalized. Created during OGP development to document OpenClaw regression analysis.
+
+---
+
+## Timeline Summary
+
+User reported that OpenClaw has been crashing non-stop for the last 24 hours after previously working without issues. Multiple agents were affected, with the gateway itself crashing repeatedly.
+
+---
+
+## Issues Identified & Fixed
+
+### 1. Cascading Authentication Failures (8:00 AM)
+
+**Symptoms:**
+- Agent failing with all configured model providers
+- Error sequence: Multiple providers failing in sequence
+- "All models failed" errors in logs
+
+**Root Causes:**
+- Kimi API: HTTP 401 - Invalid/expired API key
+- Anthropic API: HTTP 401 - Invalid API key (rate limits also hit)
+- OpenAI API: 401 - Malformed API key (env var expansion failing)
+
+**Analysis:**
+The `openclaw doctor` command appeared to have modified the configuration file, simplifying the env section and causing environment variable expansion to fail. The OpenAI provider had a misconfigured API key reference.
+
+**Fix Applied:**
+- Restored proper API key references in env section
+- Changed OpenAI provider to use environment variable references
+
+### 2. Model Configuration Corruption (Multiple Occurrences)
+
+**Symptoms:**
+- Agent configuration simplified to only primary model, no fallbacks
+- Default model referencing non-existent model ID
+- Invalid model IDs causing 404 errors
+
+**Root Cause:**
+Configuration file was being modified (likely by `openclaw doctor` command or auto-formatting) which:
+- Removed fallback models from agent configurations
+- Simplified environment variable definitions
+- Changed model references
+
+**Example Configuration Issue:**
+```json
+// Broken (no fallbacks)
+"model": {
+  "primary": "anthropic/claude-sonnet-4-6"
+}
+
+// Restored (with fallbacks)
+"model": {
+  "primary": "openai/gpt-5.4",
+  "fallbacks": [
+    "anthropic/claude-sonnet-4-6",
+    "openai/gpt-4o",
+    "fireworks/accounts/fireworks/models/kimi-k2p5"
+  ]
+}
+```
+
+### 3. OpenAI API 404 Errors (9:00-9:50 AM)
+
+**Symptoms:**
+- Continuous 404 errors on OpenAI models
+- All OpenAI models failing despite being available via API
+
+**Root Cause:**
+GPT-5.4 and newer models require the **Responses API** endpoint (`/v1/responses`) instead of the Chat Completions API endpoint (`/v1/chat/completions`). OpenClaw was using the wrong endpoint.
+
+**Evidence:**
+- Manual API query confirmed models exist: `gpt-5.4`, `gpt-5.4-2026-03-05`, `gpt-4o` all available
+- OpenAI documentation confirmed GPT-5.4 requires Responses API
+- Error pattern: 404 with no body = wrong endpoint
+
+**Fix Applied:**
+Added `"api": "openai-responses"` to OpenAI provider configuration:
+```json
+"openai": {
+  "baseUrl": "https://api.openai.com/v1",
+  "apiKey": "${PERSONAL_OPENAI_API_KEY}",
+  "api": "openai-responses",
+  "models": [...]
+}
+```
+
+**References:**
+- GitHub Issue: openclaw/openclaw#38706 - "GPT-5.4 via openai-codex OAuth uses wrong API"
+- OpenAI Docs: Responses API required for GPT-5.4+
+
+### 4. Gateway Crash - "Agent listener invoked outside active run" (12:08 PM)
+
+**Symptoms:**
+- Gateway completely unreachable
+- LaunchAgent exit status: -1
+- Error: `Unhandled promise rejection: Error: Agent listener invoked outside active run`
+
+**Stack Trace:**
+```
+at Agent.processEvents (pi-agent-core/src/agent.ts:533:10)
+at emitUpdate (exec-defaults-*.js:1524:8)
+at handleStdout (exec-defaults-*.js:1546:4)
+```
+
+**Context:**
+Crash occurred during OGP federation testing operations. Preceding log entries show:
+- Edit operations failing
+- Read operations failing for config files
+- Multiple edit retry attempts
+
+**Hypothesis:**
+The crash may be related to:
+1. OGP operations triggering edge cases in the exec/agent framework
+2. File operations failing and causing state inconsistencies
+3. Agent event processing happening outside the expected execution context
+
+**Fix Applied:**
+Gateway restart resolved the immediate issue, but underlying cause remained unclear at the time.
+
+---
+
+## Configuration Stability Concerns
+
+### Observed Pattern:
+1. Manual configuration changes applied
+2. Gateway restart
+3. Configuration file modified by unknown process
+4. Settings reverted or simplified
+5. Agents fail again
+
+### Suspected Culprits:
+- `openclaw doctor` command
+- Auto-formatting/validation on config reload
+- Hot reload mechanism modifying config
+
+---
+
+## Gateway Stability Observations
+
+### Crash Frequency:
+- Multiple gateway restarts required during debugging session
+- Many restarts over 4-hour period
+- One complete crash requiring manual intervention
+
+### Memory/CPU Usage:
+- Gateway process consistently using high CPU during startup
+- Process ID changing frequently
+
+### LaunchAgent Behavior:
+- LaunchAgent showing status `-1` during crashes
+- Sometimes showing status `0` but process not actually running
+- Restart command occasionally reports "stale process" and force-kills
+
+---
+
+## OGP-Related Observations
+
+### Timing Correlation:
+User mentioned doing OGP work and the timeline suggests:
+- OpenClaw was stable before OGP work
+- Issues began within last 24 hours
+- Gateway crash occurred during OGP federation operations
+
+### OGP Operations Observed in Logs:
+- Federation requests to Clawporate gateway
+- Agent-to-agent communication attempts
+- File operations on OGP-related files
+- Attempts to read OGP config (file not found)
+
+### Potential OGP-Related Issues:
+1. **File Operation Failures**: Multiple edit/read failures on OGP-related files
+2. **Agent Event Processing**: Crash occurred during stdout handling from supervised process
+3. **Missing Config Files**: OGP config expected but not found in multiple locations
+
+---
+
+## Mitigation Steps Applied - 5:56 PM
+
+### Changes Made to Test Crash Prevention:
+
+**1. Disabled Heartbeat Tasks**
+- Removed `heartbeat` configurations from agent defaults
+- **Hypothesis**: Hourly heartbeats triggering cron jobs that hit API failures and crashed the gateway
+
+**2. Replaced Keychain Lookups with Direct API Keys**
+- Changed from: `$(security find-generic-password ...)`
+- Changed to: Direct environment variable references
+- **Reason**: Keychain lookups repeatedly failing with env var expansion errors
+
+**3. BrainLift Plugin**
+- Already disabled (enabled: false)
+- No changes needed
+
+---
+
+## Current Working Configuration
+
+### Models:
+- **Primary**: openai/gpt-5.4 (via Responses API)
+- **Fallbacks**: anthropic/claude-sonnet-4-6, openai/gpt-4o, fireworks/kimi-k2p5
+
+### API Keys (via environment variables):
+- ANTHROPIC_API_KEY: Working
+- OPENAI_API_KEY: Working (via Responses API)
+- FIREWORKS_API_KEY: Working
+
+### Critical Config Settings:
+```json
+{
+  "models": {
+    "providers": {
+      "openai": {
+        "api": "openai-responses",
+        "baseUrl": "https://api.openai.com/v1",
+        "apiKey": "${PERSONAL_OPENAI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Open Questions
+
+1. **What triggers config file modifications?** Is it automatic or user-initiated?
+2. **Is OGP plugin causing instability?** Correlation suggests possible connection
+3. **Why are keychain lookups failing intermittently?** Sometimes work, sometimes fail
+4. **What is the expected behavior for "Agent listener invoked outside active run"?** Is this a known edge case?
+
+---
+
+## Files Modified During Session
+
+- `$HOME/.openclaw/openclaw.json` (multiple times)
+  - API key configurations
+  - Model provider settings
+  - Agent model configurations
+  - Environment variables
+
+---
+
+**Session Date**: April 7, 2026  
+**OpenClaw Version**: 2026.4.5  
+**Total Crashes**: Multiple  
+**Average Uptime Between Crashes**: 10-20 minutes  
+**Sanitized for Publication**: April 8, 2026

package/docs/federation-flow.md

@@ -290,7 +290,7 @@ Bob's OGP daemon (doorman):
 3. **Checks rate limits** - Has Alice exceeded their quota? (v0.2.0+)
 4. Verifies signature using Alice's public key
 5. Checks intent exists in registry
-6. Forwards to Bob's OpenClaw via webhook or sessions_send (v0.2.3+)
+6. Forwards to Bob's OpenClaw via the local platform delivery backend
 
 If scope check fails:
 - Response: `403 Forbidden`
@@ -303,51 +303,41 @@ If rate limit exceeded:
 
 ### OpenClaw Notification
 
-v0.2.3+ prioritizes **sessions_send** over system events for better Telegram integration:
+For human-facing federated work, the OpenClaw reference path is now an agent-turn hook rather than raw session injection:
 
 ```http
-POST /api/sessions/send HTTP/1.1
+POST /hooks/agent HTTP/1.1
 Host: bob-openclaw.local:18789
-Authorization: Bearer bob-token
+Authorization: Bearer <hooks-token>
 Content-Type: application/json
 
 {
-  "sessionKey": "agent:main:main",
-  "message": "[OGP] Message from Alice: Hello, Bob!",
-  "ogp": {
-    "from": "peer-alice",
-    "intent": "message",
-    "nonce": "550e8400-e29b-41d4-a716-446655440000",
-    "payload": {
-      "text": "Hello, Bob!"
+  "agentId": "main",
+  "text": "[OGP Federation] Alice says: Hello, Bob!",
+  "metadata": {
+    "ogp": {
+      "from": "peer-alice",
+      "intent": "message",
+      "nonce": "550e8400-e29b-41d4-a716-446655440000",
+      "payload": {
+        "text": "Hello, Bob!"
+      }
     }
   }
 }
 ```
 
-Fallback to system event if sessions_send is unavailable:
+That lets OpenClaw run a real agent turn, apply the configured human-delivery policy, and decide how to surface the result to the human.
 
-```http
-POST /api/system-event HTTP/1.1
-Host: bob-openclaw.local:18789
-Authorization: Bearer bob-token
-Content-Type: application/json
+If OGP needs direct session injection for fallback or synchronization, it uses Gateway RPC against the TLS-enabled local gateway:
 
-{
-  "text": "[OGP] Message from Alice: Hello, Bob!",
-  "sessionKey": "agent:main:main",
-  "ogp": {
-    "from": "peer-alice",
-    "intent": "message",
-    "nonce": "550e8400-e29b-41d4-a716-446655440000",
-    "payload": {
-      "text": "Hello, Bob!"
-    }
-  }
-}
+```bash
+openclaw gateway call --url wss://localhost:18789 sessions.send ...
 ```
 
-Bob's OpenClaw agent sees (via Telegram or system notification):
+`sessions.send` is still useful, but it is not the primary delivery primitive for human-facing federated work.
+
+Bob's OpenClaw agent sees the resulting human-facing output in the configured channel:
 
 ```
 [OGP] Message from Alice: Hello, Bob!

package/docs/hermes-implementation-checklist.md

@@ -1,6 +1,10 @@
 # Hermes Integration Implementation Checklist
 
 > Developer checklist for adding Hermes support to OGP
+>
+> Historical note, April 9, 2026: this file is retained as an implementation artifact.
+> Many unchecked boxes below were never backfilled after the sidecar work landed.
+> Do not use this file as the canonical current backlog. Use `CURRENT_WORK.md` and Beads instead.
 
 ## Phase 1: Sidecar Integration (Week 1)
 

package/docs/rendezvous.md

@@ -1,28 +1,27 @@
-# Rendezvous — Zero-Config Peer Discovery
+# Rendezvous — Optional Discovery And Invite Layer
 
 > Available in v0.2.14+
 
-OGP's rendezvous service lets gateways discover each other by public key — no port forwarding, no third-party tunnels, no manual URL exchange required.
+OGP's rendezvous service is an optional convenience layer for pubkey lookup and invite codes. It helps peers find each other more easily once each gateway is already publicly reachable.
 
-## The Problem It Solves
+## What It Solves
 
-For two OGP gateways to federate, both need to be publicly reachable. Without rendezvous, that means:
+For two OGP gateways to federate, both still need to be publicly reachable. Rendezvous helps by reducing coordination overhead:
 
-- Signing up for ngrok or Cloudflare Tunnel
-- Manually sharing your tunnel URL with each peer
-- Re-sharing every time the URL rotates (free tier ngrok rotates on restart)
-- Opening router ports or dealing with NAT
+- peer discovery by public key
+- invite-code UX
+- avoiding manual URL/pubkey exchange when a peer is already advertising a reachable endpoint
 
-Rendezvous collapses all of that to zero config.
+Rendezvous does **not** provide NAT traversal, UDP hole punching, or relay delivery.
 
 ## How It Works
 
-1. Your OGP daemon starts and auto-registers with the rendezvous server (`POST /register`) using your public key and current IP:port
+1. Your OGP daemon starts and auto-registers with the rendezvous server (`POST /register`) using your public key and connection hints
 2. A 30-second heartbeat keeps your registration alive (90-second TTL on the server)
 3. When you want to connect to a peer, your daemon looks them up by public key (`GET /peer/:pubkey`) and connects directly
 4. On shutdown, your daemon deregisters (`DELETE /peer/:pubkey`)
 
-The rendezvous server **never touches message content** — it only stores connection hints (IP + port). All OGP messages remain end-to-end signed between peers.
+The rendezvous server **never touches message content** — it only stores connection hints. All OGP messages remain end-to-end signed between peers.
 
 ## Configuration
 
@@ -40,7 +39,7 @@ Add the `rendezvous` block to `~/.ogp/config.json`:
 }
 ```
 
-The OGP setup wizard (`ogp setup`) will prompt for rendezvous configuration going forward.
+Rendezvous is optional. If you already have stable public URLs or are happy sharing them directly, you do not need it.
 
 ## Federation Invite Flow (v0.2.15+)
 
@@ -69,7 +68,7 @@ Output:
 Connected to a3f7k2... via rendezvous ✅
 ```
 
-That's the full flow. No pubkey, no URL, no coordination overhead.
+That's the full flow. No pubkey exchange and less coordination overhead, but the peer still needs a reachable gateway endpoint behind the lookup.
 
 ### How invite codes work
 
@@ -102,7 +101,7 @@ Public instance: `https://rendezvous.elelem.expert`
 
 ## Privacy & Trust
 
-- The rendezvous server stores only: public key, IP address, port, and last-seen timestamp
+- The rendezvous server stores only: public key, connection hints, and last-seen timestamp
 - No message content ever passes through rendezvous
 - Registrations expire after 90 seconds without a heartbeat
 - The server is open source — you can self-host if you prefer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-pcs/ogp",
-  "version": "0.3.2",
+  "version": "0.4.2",
   "description": "Open Gateway Protocol (OGP) - Peer-to-peer federation daemon for OpenClaw AI gateways with cryptographic signatures",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,6 +12,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/install-skills.js || echo 'Note: Run ogp-install-skills to install OGP skills for your AI agent'"
   },
@@ -44,13 +46,17 @@
     "package.json"
   ],
   "dependencies": {
+    "@types/ws": "^8.18.1",
     "commander": "^12.0.0",
-    "express": "^4.18.2"
+    "express": "^4.18.2",
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^20.11.0",
-    "typescript": "^5.3.3"
+    "@vitest/coverage-v8": "^4.1.3",
+    "typescript": "^5.3.3",
+    "vitest": "^4.1.3"
   },
   "engines": {
     "node": ">=18.0.0"

package/scripts/completion.bash

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+
+# OGP bash completion script
+# Auto-generated by ogp completion install
+
+_ogp_completion() {
+  local cur prev opts
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Get the first command (after ogp)
+  local cmd=""
+  if [ $COMP_CWORD -ge 1 ]; then
+    cmd="${COMP_WORDS[1]}"
+  fi
+
+  # Get the second command (for subcommands)
+  local subcmd=""
+  if [ $COMP_CWORD -ge 2 ]; then
+    subcmd="${COMP_WORDS[2]}"
+  fi
+
+  # --for flag completion (can appear anywhere)
+  if [ "$prev" = "--for" ]; then
+    local frameworks=$(ogp config list --quiet 2>/dev/null || echo "")
+    COMPREPLY=( $(compgen -W "${frameworks} all" -- ${cur}) )
+    return 0
+  fi
+
+  # Top-level commands
+  if [ $COMP_CWORD -eq 1 ]; then
+    opts="setup start stop status federation agent-comms config expose expose-stop shutdown install uninstall intent project completion"
+    COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+    return 0
+  fi
+
+  # federation subcommands
+  if [ "$cmd" = "federation" ]; then
+    if [ $COMP_CWORD -eq 2 ]; then
+      opts="list status request connect invite accept approve reject remove alias ping send scopes grant agent"
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    fi
+
+    # For federation commands that need peer-id, we could add dynamic peer completion here
+    # TODO: ogp federation list --quiet to get peer IDs/aliases
+    return 0
+  fi
+
+  # agent-comms subcommands
+  if [ "$cmd" = "agent-comms" ]; then
+    if [ $COMP_CWORD -eq 2 ]; then
+      opts="policies configure add-topic set-topic set-default remove-topic reset activity default logging"
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    fi
+    return 0
+  fi
+
+  # config subcommands
+  if [ "$cmd" = "config" ]; then
+    if [ $COMP_CWORD -eq 2 ]; then
+      opts="show set-default list enable disable frameworks"
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    fi
+
+    # For config commands that need framework ID
+    if [[ "$subcmd" == "set-default" || "$subcmd" == "enable" || "$subcmd" == "disable" ]]; then
+      if [ $COMP_CWORD -eq 3 ]; then
+        local frameworks=$(ogp config list --quiet 2>/dev/null || echo "")
+        COMPREPLY=( $(compgen -W "${frameworks}" -- ${cur}) )
+        return 0
+      fi
+    fi
+    return 0
+  fi
+
+  # intent subcommands
+  if [ "$cmd" = "intent" ]; then
+    if [ $COMP_CWORD -eq 2 ]; then
+      opts="register list remove"
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    fi
+    return 0
+  fi
+
+  # project subcommands
+  if [ "$cmd" = "project" ]; then
+    if [ $COMP_CWORD -eq 2 ]; then
+      opts="create join list remove contribute query status request-join send-contribution query-peer status-peer delete"
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    fi
+    return 0
+  fi
+
+  # completion subcommands
+  if [ "$cmd" = "completion" ]; then
+    if [ $COMP_CWORD -eq 2 ]; then
+      opts="install"
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    fi
+    return 0
+  fi
+
+  # expose subcommands
+  if [ "$cmd" = "expose" ]; then
+    if [ "$prev" = "-m" ] || [ "$prev" = "--method" ]; then
+      opts="cloudflared ngrok"
+      COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+      return 0
+    fi
+    return 0
+  fi
+
+  return 0
+}
+
+complete -F _ogp_completion ogp