@dp-pcs/ogp 0.3.3 → 0.4.3

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/docs/scopes.md

@@ -19,8 +19,8 @@ Your gateway advertises its capabilities in the federation card at `/.well-known
   "version": "0.2.3",
   "displayName": "David's Gateway",
   "capabilities": {
-    "intents": ["message", "task-request", "status-update", "agent-comms", "project"],
-    "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"]
   }
 }
 ```
@@ -28,7 +28,7 @@ Your gateway advertises its capabilities in the federation card at `/.well-known
 This tells other gateways what you **can** support, not what you **will** grant.
 
 Capabilities are automatically populated from:
-- **Built-in intents**: `message`, `task-request`, `status-update`, `agent-comms`, `project`
+- **Built-in intents**: `message`, `task-request`, `status-update`, `agent-comms`, `project.join`, `project.contribute`, `project.query`, `project.status`
 - **Custom intents**: Registered via `ogp intent register`
 - **Features**: Protocol features your gateway supports
 
@@ -205,25 +205,25 @@ ogp federation approve alice \
   --rate 50/3600
 ```
 
-## Project Intent
+## Project Intents
 
-The `project` intent enables collaborative project management across federated peers.
+Project collaboration is enforced through four exact runtime intents, not a singular `project` scope.
 
 ### Project Actions
 
 | Action | Description | Rate Limit Recommended |
 |--------|-------------|------------------------|
-| `contribute` | Send contribution to peer's project | 100/hour |
-| `query` | Query peer's project contributions | 50/hour |
-| `request-join` | Request to join peer's project | 10/hour |
-| `status` | Get project status from peer | 20/hour |
+| `project.join` | Join or create a shared project context | 10/hour |
+| `project.contribute` | Send a contribution to a peer's project | 100/hour |
+| `project.query` | Query peer project contributions | 50/hour |
+| `project.status` | Get peer project status | 20/hour |
 
 ### Grant Project Access
 
 ```bash
-# Grant project collaboration access
+# Grant full project collaboration access
 ogp federation approve alice \
-  --intents project \
+  --intents project.join,project.contribute,project.query,project.status \
   --rate 100/3600
 ```
 
@@ -260,9 +260,9 @@ ogp federation approve bob \
 ### Project Collaboration
 
 ```bash
-# Grant project and agent-comms for team collaboration
+# Grant project collaboration intents plus agent-comms for team coordination
 ogp federation approve charlie \
-  --intents agent-comms,project \
+  --intents agent-comms,project.join,project.contribute,project.query,project.status \
   --topics project-updates,planning \
   --rate 200/3600
 ```

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@dp-pcs/ogp",
-  "version": "0.3.3",
+  "version": "0.4.3",
   "description": "Open Gateway Protocol (OGP) - Peer-to-peer federation daemon for OpenClaw AI gateways with cryptographic signatures",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "ogp": "./dist/cli.js",
-    "ogp-install-skills": "./scripts/install-skills.js"
+    "ogp": "dist/cli.js",
+    "ogp-install-skills": "scripts/install-skills.js"
   },
   "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'"
   },
@@ -29,7 +31,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dp-pcs/ogp.git"
+    "url": "git+https://github.com/dp-pcs/ogp.git"
   },
   "homepage": "https://github.com/dp-pcs/ogp#readme",
   "bugs": {
@@ -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

package/scripts/completion.zsh

@@ -0,0 +1,372 @@
+#compdef ogp
+
+# OGP zsh completion script
+# Auto-generated by ogp completion install
+
+_ogp() {
+  local -a frameworks peers
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+
+  # Get frameworks for --for flag
+  frameworks=(${(f)"$(ogp config list --quiet 2>/dev/null)"} all)
+
+  _arguments -C \
+    '(- *)'{-h,--help}'[Show help]' \
+    '(- *)'{-v,--version}'[Show version]' \
+    '--for[Select framework]:framework:($frameworks)' \
+    '1: :->command' \
+    '*::arg:->args'
+
+  case "$state" in
+    command)
+      _arguments '1:command:((
+        setup\:"Initialize OGP configuration"
+        start\:"Start OGP daemon"
+        stop\:"Stop OGP daemon"
+        status\:"Show daemon status"
+        federation\:"Manage federation"
+        agent-comms\:"Configure agent-to-agent messaging"
+        config\:"Manage configuration"
+        expose\:"Expose daemon via tunnel"
+        expose-stop\:"Stop background tunnel"
+        shutdown\:"Stop daemon and tunnel"
+        install\:"Install LaunchAgent (macOS)"
+        uninstall\:"Uninstall LaunchAgent (macOS)"
+        intent\:"Manage custom intents"
+        project\:"Manage project contexts"
+        completion\:"Install completion scripts"
+      ))'
+      ;;
+    args)
+      case ${words[1]} in
+        federation)
+          _ogp_federation
+          ;;
+        agent-comms)
+          _ogp_agent_comms
+          ;;
+        config)
+          _ogp_config
+          ;;
+        intent)
+          _ogp_intent
+          ;;
+        project)
+          _ogp_project
+          ;;
+        completion)
+          _ogp_completion
+          ;;
+        expose)
+          _ogp_expose
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ogp_federation() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+
+  _arguments '1:subcommand:((
+    list\:"List all peers"
+    status\:"Show federation status and alias mappings"
+    request\:"Send federation request to a peer"
+    connect\:"Connect to peer by public key via rendezvous"
+    invite\:"Generate invite token to share with peer"
+    accept\:"Accept peer invite token and connect"
+    approve\:"Approve pending federation request"
+    reject\:"Reject pending federation request"
+    remove\:"Remove peer from federation list"
+    alias\:"Set user-friendly alias for peer"
+    ping\:"Ping peer gateway to test connectivity"
+    send\:"Send message to federated peer"
+    scopes\:"Show scope grants for peer"
+    grant\:"Update scope grants for approved peer"
+    agent\:"Send agent-comms message to peer"
+  ))' \
+  '*::arg:->args'
+
+  case "$state" in
+    args)
+      case ${words[1]} in
+        list)
+          _arguments \
+            '(-s --status)'{-s,--status}'[Filter by status]:status:(pending approved rejected removed)'
+          ;;
+        request)
+          _arguments \
+            '1:peer-url:' \
+            '2:peer-id::' \
+            '(-a --alias)'{-a,--alias}'[User-friendly alias]:alias:' \
+            '--petname[Deprecated - use --alias]:petname:'
+          ;;
+        connect|accept)
+          _arguments \
+            '1:identifier:' \
+            '(-a --alias)'{-a,--alias}'[User-friendly alias]:alias:' \
+            '--petname[Deprecated - use --alias]:petname:'
+          ;;
+        approve)
+          _arguments \
+            '1:peer-id:' \
+            '--intents[Comma-separated intents to grant]:intents:' \
+            '--rate[Rate limit as requests/seconds]:rate:' \
+            '--topics[Comma-separated topics for agent-comms]:topics:'
+          ;;
+        reject|remove|scopes|alias)
+          _arguments '1:peer-id:'
+          ;;
+        send)
+          _arguments \
+            '1:peer-id:' \
+            '2:intent:' \
+            '3:payload:'
+          ;;
+        grant)
+          _arguments \
+            '1:peer-id:' \
+            '--intents[Comma-separated intents to grant]:intents:' \
+            '--rate[Rate limit as requests/seconds]:rate:' \
+            '--topics[Comma-separated topics for agent-comms]:topics:'
+          ;;
+        agent)
+          _arguments \
+            '1:peer-id:' \
+            '2:topic:' \
+            '3:message:' \
+            '(-p --priority)'{-p,--priority}'[Priority level]:priority:(low normal high)' \
+            '(-c --conversation)'{-c,--conversation}'[Conversation ID]:conversation-id:' \
+            '(-w --wait)'{-w,--wait}'[Wait for reply]' \
+            '(-t --timeout)'{-t,--timeout}'[Reply timeout in milliseconds]:timeout:'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ogp_agent_comms() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+
+  _arguments '1:subcommand:((
+    policies\:"Show response policies"
+    configure\:"Configure response policies"
+    add-topic\:"Add topic to peer response policy"
+    set-topic\:"Set topic policy for peer"
+    set-default\:"Set per-peer default level"
+    remove-topic\:"Remove topic from peer policy"
+    reset\:"Reset peer policy to global defaults"
+    activity\:"Show agent-comms activity log"
+    default\:"Set default response level for unknown topics"
+    logging\:"Enable or disable activity logging"
+  ))' \
+  '*::arg:->args'
+
+  case "$state" in
+    args)
+      case ${words[1]} in
+        policies|activity)
+          _arguments '1:peer-id::'
+          ;;
+        configure)
+          _arguments \
+            '1:peer-ids::' \
+            '--global[Configure global default policies]' \
+            '--topics[Comma-separated topics]:topics:' \
+            '--level[Response level]:level:(full summary escalate deny off)' \
+            '--notes[Policy notes]:notes:'
+          ;;
+        add-topic)
+          _arguments \
+            '1:peer-id:' \
+            '2:topic:' \
+            '--level[Response level]:level:(full summary escalate deny off)' \
+            '--notes[Topic notes]:notes:'
+          ;;
+        set-topic)
+          _arguments \
+            '1:peer-id:' \
+            '2:topic:' \
+            '3:level:(full summary escalate deny off)' \
+            '--notes[Topic notes]:notes:'
+          ;;
+        set-default)
+          _arguments \
+            '1:peer-id:' \
+            '2:level:(full summary escalate deny off)'
+          ;;
+        remove-topic|reset)
+          _arguments '1:peer-id:' '2:topic::'
+          ;;
+        default)
+          _arguments '1:level:(full summary escalate deny off)'
+          ;;
+        logging)
+          _arguments '1:state:(on off true false enable disable)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ogp_config() {
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+  local -a frameworks
+  frameworks=(${(f)"$(ogp config list --quiet 2>/dev/null)"})
+
+  _arguments '1:subcommand:((
+    show\:"Show all configured frameworks and default"
+    set-default\:"Set default framework"
+    list\:"List all frameworks"
+    enable\:"Enable a framework"
+    disable\:"Disable a framework"
+    frameworks\:"Show all detected frameworks"
+  ))' \
+  '*::arg:->args'
+
+  case "$state" in
+    args)
+      case ${words[1]} in
+        set-default|enable|disable)
+          _arguments "1:framework:($frameworks)"
+          ;;
+        list)
+          _arguments '(-q --quiet)'{-q,--quiet}'[Output framework IDs only]'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ogp_intent() {
+  _arguments '1:subcommand:((
+    register\:"Register new intent handler"
+    list\:"List all registered intents"
+    remove\:"Remove registered intent"
+  ))' \
+  '*::arg:->args'
+
+  case "$state" in
+    args)
+      case ${words[1]} in
+        register)
+          _arguments \
+            '1:name:' \
+            '--script[Path to handler script]:script:_files' \
+            '--description[Intent description]:description:'
+          ;;
+        remove)
+          _arguments '1:name:'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ogp_project() {
+  _arguments '1:subcommand:((
+    create\:"Create new project locally"
+    join\:"Join existing project"
+    list\:"List all local projects"
+    remove\:"Remove local project"
+    contribute\:"Add contribution to project"
+    query\:"Query project contributions"
+    status\:"Show project status overview"
+    request-join\:"Request to join project from peer"
+    send-contribution\:"Send contribution to peer project"
+    query-peer\:"Query peer project contributions"
+    status-peer\:"Request project status from peer"
+    delete\:"Delete local project and all contributions"
+  ))' \
+  '*::arg:->args'
+
+  case "$state" in
+    args)
+      case ${words[1]} in
+        create)
+          _arguments \
+            '1:project-id:' \
+            '2:project-name:' \
+            '--description[Project description]:description:'
+          ;;
+        join)
+          _arguments \
+            '1:project-id:' \
+            '2:project-name::' \
+            '--create[Create project if not exists]' \
+            '--description[Project description]:description:'
+          ;;
+        remove|status|delete)
+          _arguments \
+            '1:project-id:' \
+            '--force[Skip confirmation prompt]'
+          ;;
+        contribute)
+          _arguments \
+            '1:project-id:' \
+            '2:type:' \
+            '3:summary:' \
+            '--metadata[Additional structured data as JSON]:metadata:' \
+            '--local-only[Skip auto-push to federated peers]'
+          ;;
+        query)
+          _arguments \
+            '1:project-id:' \
+            '--type[Filter by entry type]:type:' \
+            '--topic[Filter by entry type (alias)]:topic:' \
+            '--author[Filter by author]:author:' \
+            '--search[Search by text content]:search:' \
+            '--limit[Maximum results]:limit:'
+          ;;
+        request-join)
+          _arguments \
+            '1:peer-id:' \
+            '2:project-id:' \
+            '3:project-name:' \
+            '--description[Project description]:description:'
+          ;;
+        send-contribution)
+          _arguments \
+            '1:peer-id:' \
+            '2:project-id:' \
+            '3:type:' \
+            '4:summary:' \
+            '--metadata[Additional structured data as JSON]:metadata:'
+          ;;
+        query-peer)
+          _arguments \
+            '1:peer-id:' \
+            '2:project-id:' \
+            '--type[Filter by entry type]:type:' \
+            '--topic[Filter by entry type (alias)]:topic:' \
+            '--author[Filter by author]:author:' \
+            '--limit[Maximum results]:limit:' \
+            '--timeout[Response timeout in milliseconds]:timeout:'
+          ;;
+        status-peer)
+          _arguments \
+            '1:peer-id:' \
+            '2:project-id:'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ogp_completion() {
+  _arguments '1:subcommand:((
+    install\:"Install completion scripts for current shell"
+  ))'
+}
+
+_ogp_expose() {
+  _arguments \
+    '(-m --method)'{-m,--method}'[Tunnel method]:method:(cloudflared ngrok)' \
+    '(-b --background)'{-b,--background}'[Run in background]'
+}
+
+_ogp