@dp-pcs/ogp 0.3.3 → 0.4.3

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/cloudflare-named-tunnel-setup.md

@@ -0,0 +1,126 @@
+# Cloudflare Named Tunnel Setup for OGP
+
+Use this when you already have a domain managed in Cloudflare and want a stable public OGP URL like `ogp.example.com`.
+
+This guide assumes:
+- OGP is running locally on port `18790`
+- You already control the domain in Cloudflare
+- You are setting up a locally managed named tunnel with `cloudflared`
+
+## What this does
+
+It creates a stable public hostname such as `https://ogp.example.com` and forwards it to your local OGP daemon at `http://localhost:18790`.
+
+After this is working, set your OGP `gatewayUrl` to the same public URL.
+
+## Copy-paste setup
+
+Replace `ogp.yourdomain.com` below with your real hostname.
+
+```bash
+# 1. Install cloudflared if needed
+brew install cloudflared
+
+# 2. Login to Cloudflare in the browser
+cloudflared tunnel login
+
+# 3. Create a named tunnel called "ogp"
+cloudflared tunnel create ogp
+
+# 4. Route a public hostname to the tunnel
+cloudflared tunnel route dns ogp ogp.yourdomain.com
+
+# 5. Create the config directory if needed
+mkdir -p ~/.cloudflared
+
+# 6. List tunnels so you can copy the UUID for "ogp"
+cloudflared tunnel list
+```
+
+Create `~/.cloudflared/config.yml` and replace `TUNNEL_UUID_HERE` with the real UUID from `cloudflared tunnel list`.
+
+```yaml
+tunnel: TUNNEL_UUID_HERE
+credentials-file: /Users/YOUR_USERNAME/.cloudflared/TUNNEL_UUID_HERE.json
+
+ingress:
+  - hostname: ogp.yourdomain.com
+    service: http://localhost:18790
+  - service: http_status:404
+```
+
+Then start OGP and test the tunnel:
+
+```bash
+# 7. Start OGP
+ogp start --background
+
+# 8. Run the tunnel in the foreground once to test
+cloudflared tunnel run ogp
+```
+
+In a second terminal:
+
+```bash
+# 9. Verify the public OGP card is reachable
+curl -s https://ogp.yourdomain.com/.well-known/ogp
+```
+
+## Set gatewayUrl
+
+Edit `~/.ogp/config.json` and make sure it includes:
+
+```json
+{
+  "gatewayUrl": "https://ogp.yourdomain.com"
+}
+```
+
+Then restart OGP:
+
+```bash
+ogp stop
+ogp start --background
+curl -s https://ogp.yourdomain.com/.well-known/ogp
+```
+
+The returned JSON should show the same `gatewayUrl`.
+
+## Make the tunnel persistent
+
+Once the foreground test works:
+
+```bash
+cloudflared service install
+```
+
+Then start the service using your system service manager.
+
+## Common problems
+
+If `cloudflared tunnel route dns` fails:
+- The hostname may already have an existing DNS record
+- The domain may not actually be managed by Cloudflare yet
+
+If `curl https://ogp.yourdomain.com/.well-known/ogp` fails:
+- OGP may not be running on port `18790`
+- The hostname in `config.yml` may be wrong
+- `gatewayUrl` in `~/.ogp/config.json` may still be blank or stale
+- The tunnel may not be running yet
+
+## Minimal success check
+
+These both need to be true:
+
+```bash
+curl -s http://localhost:18790/.well-known/ogp
+curl -s https://ogp.yourdomain.com/.well-known/ogp
+```
+
+And the public card should contain:
+
+```json
+{
+  "gatewayUrl": "https://ogp.yourdomain.com"
+}
+```

package/docs/federation-flow.md

@@ -33,8 +33,8 @@ Host: peer.example.com
   "publicKey": "302a300506032b6570032100abc123...",
   "agentId": "main",
   "capabilities": {
-    "intents": ["message", "task-request", "status-update", "agent-comms"],
-    "features": ["scope-negotiation", "reply-callback", "project-intent"]
+    "intents": ["message", "task-request", "status-update", "agent-comms", "project.join", "project.contribute", "project.query", "project.status"],
+    "features": ["scope-negotiation", "reply-callback"]
   },
   "endpoints": {
     "request": "https://peer.example.com/federation/request",
@@ -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!
@@ -470,7 +460,7 @@ Content-Type: application/json
       "action": "contribute",
       "projectId": "shared-app",
       "contribution": {
-        "topic": "progress",
+        "entryType": "progress",
         "summary": "Completed authentication system",
         "metadata": {
           "files": ["src/auth.ts", "src/jwt.ts"],
@@ -495,7 +485,7 @@ Bob's daemon:
 Bob sees:
 
 ```
-[OGP Project] Alice contributed to shared-app (progress): Completed authentication system
+[OGP Project] Alice contributed to shared-app (entry type: progress): Completed authentication system
 ```
 
 ### Alice Queries Bob's Project
@@ -549,13 +539,13 @@ Content-Type: application/json
       "projectName": "Shared Mobile App",
       "contributions": [
         {
-          "topic": "progress",
+          "entryType": "progress",
           "summary": "Deployed staging environment",
           "author": "peer-bob",
           "timestamp": "2026-03-24T10:00:00Z"
         },
         {
-          "topic": "blocker",
+          "entryType": "blocker",
           "summary": "Waiting for API key approval",
           "author": "peer-bob",
           "timestamp": "2026-03-23T15:30:00Z"

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/project-intent-testing.md

@@ -0,0 +1,97 @@
+# Project Intent Testing
+
+This repo now includes a runnable local project-intent harness:
+
+```bash
+npm run test:project-intents
+```
+
+The harness creates two isolated local gateways with separate `OGP_HOME` directories, federates them over localhost, and exercises the real project commands:
+
+- `federation request`
+- `federation approve`
+- `project create`
+- `project contribute --local-only`
+- `project request-join`
+- `project send-contribution`
+- `project query-peer`
+- `project status-peer`
+
+## What It Verifies
+
+The automated run checks these behaviors:
+
+1. Two local daemons can boot independently.
+2. Federation approval completes between them.
+3. The project owner can create a local project and persist local contributions.
+4. A non-member peer cannot query the project before joining.
+5. The peer can join the project through `project.join`.
+6. The joined peer can send a remote contribution through `project.contribute`.
+7. The joined peer can query the owner project through `project.query`.
+8. The status request path for `project.status` succeeds at the transport level.
+
+## Useful Variants
+
+Keep the temp state and logs for inspection:
+
+```bash
+npm run test:project-intents -- --keep-state
+```
+
+Use a custom root or ports:
+
+```bash
+npm run test:project-intents -- \
+  --root /tmp/ogp-project-intent-test \
+  --alpha-port 18990 \
+  --beta-port 18991
+```
+
+Skip the TypeScript rebuild when `dist/` is already current:
+
+```bash
+npm run test:project-intents -- --skip-build
+```
+
+## Manual Checks
+
+If you want to replay the flow by hand, the harness prints the exact commands it used. These are the most valuable checks:
+
+1. Membership isolation:
+   `project query-peer` should fail before `project request-join`.
+2. Membership grant:
+   `project request-join` should create or update the project on the requester and add the remote member on the owner.
+3. Data flow:
+   `project send-contribution` should create a new contribution on the owner gateway.
+4. Remote visibility:
+   `project query-peer` should return the contribution after join succeeds.
+5. Local persistence:
+   `projects.json` under each `OGP_HOME` should reflect the expected project and topic state.
+
+## Interpreting Success
+
+Project intents are working if all of the following are true:
+
+- both daemons answer `/.well-known/ogp`
+- both peers end up `approved` in `peers.json`
+- the owner `projects.json` contains the remote member after join
+- the owner `projects.json` contains the remote contribution after send
+- pre-join query fails and post-join query succeeds
+
+## Known Testing Nuance
+
+`project status-peer` currently confirms that the request was sent, but it is not the best content-verification command because the CLI does not format the returned status payload. Treat it as a transport-path check, and use `project query-peer`, `project status`, `projects.json`, and daemon logs for stronger validation.
+
+For controlled runs, `project contribute --local-only` is still useful when you want to inspect local state before any federation traffic. The default auto-sync path now limits fan-out to approved peers who are explicit members of the project.
+
+## File Transfer
+
+OGP project intents do not currently implement first-class file transfer. Small structured metadata is fine, but real file movement would need explicit protocol support such as:
+
+- file manifests with name, size, MIME type, and hash
+- signed download URLs
+- chunking or streaming for larger payloads
+- size limits and approval controls
+- storage and retention rules
+
+For now, the practical pattern is to transfer references, hashes, and URLs through project intents rather than raw file contents.

package/docs/quickstart.md

@@ -20,6 +20,14 @@ After installation, install the OGP skills for Claude Code:
 ogp-install-skills
 ```
 
+Then verify the installed skill versions:
+
+```bash
+rg -n '^version:' ~/.openclaw/skills/ogp*/SKILL.md ~/.claude/skills/ogp*/SKILL.md 2>/dev/null
+```
+
+For the current `0.4.2` release line, expect `ogp` `2.6.0`, `ogp-agent-comms` `0.6.0`, and `ogp-project` `2.2.0`.
+
 ## Step 2: Configure
 
 Run the interactive setup:
@@ -137,8 +145,8 @@ You should see:
   "gatewayUrl": "https://abc-def-123.trycloudflare.com",
   "publicKey": "302a300506032b6570032100...",
   "capabilities": {
-    "intents": ["message", "task-request", "status-update", "agent-comms"],
-    "features": ["scope-negotiation", "reply-callback", "project-intent"]
+    "intents": ["message", "task-request", "status-update", "agent-comms", "project.join", "project.contribute", "project.query", "project.status"],
+    "features": ["scope-negotiation", "reply-callback"]
   },
   "endpoints": {
     "request": "https://abc-def-123.trycloudflare.com/federation/request",
@@ -426,8 +434,8 @@ ogp federation scopes <peer-id>
 
 # Projects
 ogp project create <id> <name> [--description "..."]
-ogp project contribute <id> <topic> <summary>
-ogp project query <id> [--limit 10] [--topic <topic>]
+ogp project contribute <id> <type> <summary>
+ogp project query <id> [--limit 10] [--type <type>]
 ogp project status <id>
 
 # Intents