clawdentity 0.0.25 → 0.0.26

package/package.json

@@ -1,18 +1,10 @@
 {
   "name": "clawdentity",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vrknetha/clawdentity"
-  },
-  "bugs": {
-    "url": "https://github.com/vrknetha/clawdentity/issues"
-  },
-  "homepage": "https://github.com/vrknetha/clawdentity#readme",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {

package/skill-bundle/openclaw-skill/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clawdentity_openclaw_relay
 description: This skill should be used when the user asks to "set up Clawdentity relay", "pair two agents", "verify an agent token", "rotate API key", "refresh agent auth", "revoke an agent", "troubleshoot relay", "uninstall connector service", "check relay health", "run relay doctor", "test relay connection", "send relay test", "install relay skill", "bootstrap registry", "create onboarding invite", "decommission agent", or needs OpenClaw relay onboarding, lifecycle management, or pairing workflows.
-version: 0.3.0
+version: 0.3.1
 ---
 
 # Clawdentity OpenClaw Relay Skill
@@ -163,13 +163,10 @@ Use `--no-runtime-start` when the connector runs as a separate container or proc
 - `clawdentity pair start <agent-name> --qr --ttl-seconds <seconds>`
 - `clawdentity pair start <agent-name> --qr --wait`
 - `clawdentity pair start <agent-name> --qr --wait --wait-seconds <seconds> --poll-interval-seconds <seconds>`
-- `clawdentity pair start <agent-name> --qr --allow-responder <did:claw:agent:...>`
-- `clawdentity pair start <agent-name> --qr --callback-url <https://...>`
 - `clawdentity pair confirm <agent-name> --qr-file <path>`
 - `clawdentity pair confirm <agent-name> --ticket <clwpair1_...>`
 - `clawdentity pair status <agent-name> --ticket <clwpair1_...>`
 - `clawdentity pair status <agent-name> --ticket <clwpair1_...> --wait`
-- `clawdentity pair recover <agent-name>`
 
 ### Token verification
 - `clawdentity verify <tokenOrFile>`
@@ -261,6 +258,9 @@ Use `--no-runtime-start` when the connector runs as a separate container or proc
 - At this point the agent is ready to start pairing or accept pairing.
 
 8. Pairing phase (separate from onboarding).
+- Prerequisites (must be satisfied before any `pair` command):
+  - `humanName` must be set in local config. It is set automatically by `invite redeem --display-name`; if missing, set it with `clawdentity config set humanName <name>`. If absent, CLI fails with `CLI_PAIR_HUMAN_NAME_MISSING`.
+  - Proxy URL is auto-resolved by CLI (env → config → registry metadata). Do not ask the user for a proxy URL.
 - Required default initiator flow:
   - `clawdentity pair start <agent-name> --qr --wait`
   - Optional overrides: `--ttl-seconds <seconds>`, `--qr-output <path>`, `--wait-seconds <seconds>`, `--poll-interval-seconds <seconds>`
@@ -273,8 +273,9 @@ Use `--no-runtime-start` when the connector runs as a separate container or proc
   - Cannot provide both `--qr-file` and `--ticket` simultaneously.
 - Pair confirm auto-saves peer DID/proxy mapping locally from QR ticket metadata.
 - Pair start/confirm/status exchange profile metadata:
-  - `initiatorProfile = { agentName, humanName }`
-  - `responderProfile = { agentName, humanName }`
+  - `initiatorProfile = { agentName, humanName, proxyOrigin? }`
+  - `responderProfile = { agentName, humanName, proxyOrigin? }`
+  - These are NOT CLI flags. The CLI auto-constructs them from `config.humanName` and the `<agent-name>` argument. Do not pass or ask for these values.
 - Local peer entries in `~/.clawdentity/peers.json` should include:
   - `did`
   - `proxyUrl`
@@ -284,11 +285,7 @@ Use `--no-runtime-start` when the connector runs as a separate container or proc
   - `clawdentity pair status <agent-name> --ticket <clwpair1_...> --wait`
   - This persists the peer on initiator after responder confirmation.
 - Default wait timeout is 300 seconds with 3-second polling.
-- Wait flow is resilient (adaptive polling + transient retries) and persists pending ticket state per agent.
-- If wait times out/cancels/fails due repeated transients, preferred recovery is:
-  - `clawdentity pair recover <agent-name>`
-- Manual fallback remains:
-  - `clawdentity pair status <agent-name> --ticket <clwpair1_...> --wait`
+- If `CLI_PAIR_STATUS_WAIT_TIMEOUT` is thrown: the responder did not confirm in time. Recovery: re-run `clawdentity pair start <agent-name> --qr --wait` to generate a new ticket.
 - Confirm pairing success, then run `clawdentity openclaw relay test`.
 - **Validate:** `~/.clawdentity/peers.json` contains the new peer alias entry.
 
@@ -389,6 +386,9 @@ Do not ask for relay invite codes.
 Do not ask for `clawd1_...` values.
 Do not state that API key is required before invite redeem.
 Do not suggest switching endpoints unless user explicitly asks for endpoint changes.
+Do not ask for proxy URL — it is auto-resolved by CLI from env, config, and registry metadata.
+Do not ask for `initiatorProfile` or `responderProfile` — CLI auto-constructs these internally.
+Do not re-ask for human display name if onboarding (invite redeem) was already completed.
 
 ## Failure Handling
 
@@ -400,12 +400,11 @@ Do not suggest switching endpoints unless user explicitly asks for endpoint chan
 ### Pairing errors
 - `PROXY_PAIR_TICKET_NOT_FOUND`: ticket invalid or expired. Request a new ticket from initiator.
 - `PROXY_PAIR_TICKET_EXPIRED`: ticket has expired. Request a new ticket.
-- `PROXY_PAIR_TICKET_ALREADY_CONFIRMED`: ticket replayed; pairing already completed earlier.
-- `CLI_PAIR_STATUS_WAIT_TIMEOUT`: responder did not confirm before deadline. Run `pair recover` (preferred) or `pair status --ticket ... --wait`.
-- `CLI_PAIR_STATUS_POLL_FAILED`: transient polling failures exceeded retry budget. Run `pair recover`.
-- `CLI_PAIR_STATUS_WAIT_CANCELLED`: wait interrupted (SIGINT). Run `pair recover`.
+- `CLI_PAIR_STATUS_WAIT_TIMEOUT`: responder did not confirm in time. Re-run `pair start`.
 - `CLI_PAIR_CONFIRM_INPUT_CONFLICT`: cannot provide both `--ticket` and `--qr-file`. Use one path only.
 - `CLI_PAIR_PROXY_URL_MISMATCH`: local `proxyUrl` does not match registry metadata. Rerun `clawdentity invite redeem <clw_inv_...>`.
+- `CLI_PAIR_HUMAN_NAME_MISSING`: local config is missing `humanName`. Set via `clawdentity invite redeem <clw_inv_...> --display-name <name>` or `clawdentity config set humanName <name>`.
+- `CLI_PAIR_TICKET_ISSUER_MISMATCH`: pairing ticket was issued by a different proxy than the currently configured one. Set `proxyUrl` to match the ticket issuer: `clawdentity config set proxyUrl <issuer-url>`.
 - Responder shows peer but initiator does not:
   - Cause: initiator started pairing without `--wait`.
   - Fix: run `clawdentity pair status <initiator-agent> --ticket <clwpair1_...> --wait` on initiator.

package/skill-bundle/openclaw-skill/skill/references/clawdentity-protocol.md

@@ -65,6 +65,8 @@ Current pairing contract is ticket-based with CLI support:
 }
 ```
 
+> **Agent note:** `initiatorProfile` is auto-constructed by CLI from `config.humanName` and the `<agent-name>` argument. Do not pass or ask for this value.
+
 2. Responder confirms pairing:
    - CLI: `clawdentity pair confirm <agent-name> --qr-file <path>`
    - proxy route: `POST /pair/confirm`
@@ -82,6 +84,8 @@ Current pairing contract is ticket-based with CLI support:
 }
 ```
 
+> **Agent note:** `responderProfile` is auto-constructed by CLI from `config.humanName` and the `<agent-name>` argument. Do not pass or ask for this value.
+
 Rules:
 - `ticket` is one-time and expires (default 5 minutes, max 15 minutes).
 - Confirm establishes mutual trust for the initiator/responder pair.
@@ -177,6 +181,8 @@ CLI resolves proxy URL in this order (first non-empty wins):
 3. Registry metadata from `GET /v1/metadata`
 4. Error when configured proxy does not match metadata (`CLI_PAIR_PROXY_URL_MISMATCH`) or metadata lookup fails
 
+> **Agent note:** Proxy URL resolution is fully automatic. Do not ask the user for a proxy URL. The CLI resolves it from env, config, or registry metadata without user input.
+
 ### Metadata expectation
 
 Registry metadata (`/v1/metadata`) should return a valid `proxyUrl`.
@@ -229,7 +235,7 @@ The connector `deliver` frame includes `fromAgentDid` as a top-level field. Inbo
 | 503 | `PROXY_PAIR_OWNERSHIP_UNAVAILABLE` | Registry ownership lookup unavailable | Check proxy/registry service auth configuration |
 | — | `CLI_PAIR_AGENT_NOT_FOUND` | Agent ait.jwt or secret.key missing/empty | Run `agent create` or `agent auth refresh` |
 | — | `CLI_PAIR_HUMAN_NAME_MISSING` | Local config is missing `humanName` | Set via `invite redeem` or config |
-| — | `CLI_PAIR_PROXY_URL_REQUIRED` | Proxy URL could not be resolved | Run `invite redeem` or set `CLAWDENTITY_PROXY_URL` |
+| — | `CLI_PAIR_PROXY_URL_INVALID` | Configured proxy URL is malformed | Fix proxy URL: `clawdentity config set proxyUrl <url>` |
 | — | `CLI_PAIR_START_INVALID_TTL` | ttlSeconds must be a positive integer | Use valid `--ttl-seconds` value |
 | — | `CLI_PAIR_INVALID_PROXY_URL` | Proxy URL is invalid | Fix proxy URL in config |
 | — | `CLI_PAIR_REQUEST_FAILED` | Unable to connect to proxy URL | Check DNS, firewall, proxy URL |
@@ -250,6 +256,7 @@ The connector `deliver` frame includes `fromAgentDid` as a top-level field. Inbo
 | — | `CLI_PAIR_CONFIRM_FAILED` | Generic pair confirm failure | Retry with new ticket |
 | — | `CLI_PAIR_CONFIRM_QR_FILE_INVALID` | QR image file corrupt or unsupported | Request new QR from initiator |
 | — | `CLI_PAIR_CONFIRM_QR_FILE_REQUIRED` | QR path unusable | Verify file path and format |
+| — | `CLI_PAIR_TICKET_ISSUER_MISMATCH` | Ticket issuer does not match configured proxy URL | `clawdentity config set proxyUrl <issuer-url>` and retry |
 
 ### `pair status` errors
 
@@ -259,6 +266,8 @@ The connector `deliver` frame includes `fromAgentDid` as a top-level field. Inbo
 | — | `CLI_PAIR_STATUS_WAIT_TIMEOUT` | Wait polling timed out | Generate new ticket via `pair start` |
 | — | `CLI_PAIR_STATUS_FORBIDDEN` | 403 on status check — ownership mismatch | Verify correct agent |
 | — | `CLI_PAIR_STATUS_TICKET_REQUIRED` | Missing ticket argument | Provide `--ticket <clwpair1_...>` |
+| — | `CLI_PAIR_STATUS_WAIT_INVALID` | Wait/poll option is not a positive integer | Use a valid positive integer for `--wait-seconds` or `--poll-interval-seconds` |
+| — | `CLI_PAIR_TICKET_ISSUER_MISMATCH` | Ticket issuer does not match configured proxy URL | `clawdentity config set proxyUrl <issuer-url>` and retry |
 
 ### Peer persistence errors