clawdentity 0.0.23 → 0.0.25

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "clawdentity",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "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": {
@@ -21,6 +29,17 @@
     "postinstall.mjs",
     "skill-bundle"
   ],
+  "scripts": {
+    "build": "pnpm -F @clawdentity/openclaw-skill build && pnpm run sync:skill-bundle && pnpm run verify:skill-bundle && tsup",
+    "format": "biome format .",
+    "lint": "biome lint .",
+    "prepack": "pnpm run build",
+    "postinstall": "node ./postinstall.mjs",
+    "sync:skill-bundle": "node ./scripts/sync-skill-bundle.mjs",
+    "verify:skill-bundle": "node ./scripts/verify-skill-bundle.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
     "commander": "^13.1.0",
     "jsqr": "^1.4.0",
@@ -29,21 +48,11 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "@clawdentity/connector": "workspace:*",
+    "@clawdentity/protocol": "workspace:*",
+    "@clawdentity/sdk": "workspace:*",
     "@types/node": "^22.18.11",
     "@types/pngjs": "^6.0.5",
-    "@types/qrcode": "^1.5.6",
-    "@clawdentity/protocol": "0.0.0",
-    "@clawdentity/connector": "0.0.0",
-    "@clawdentity/sdk": "0.0.0"
-  },
-  "scripts": {
-    "build": "pnpm -F @clawdentity/openclaw-skill build && pnpm run sync:skill-bundle && pnpm run verify:skill-bundle && tsup",
-    "format": "biome format .",
-    "lint": "biome lint .",
-    "postinstall": "node ./postinstall.mjs",
-    "sync:skill-bundle": "node ./scripts/sync-skill-bundle.mjs",
-    "verify:skill-bundle": "node ./scripts/verify-skill-bundle.mjs",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "@types/qrcode": "^1.5.6"
   }
-}
+}

package/postinstall.mjs

@@ -1,15 +1,24 @@
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = dirname(fileURLToPath(import.meta.url));
 const bundledPostinstallPath = join(packageRoot, "dist", "postinstall.js");
 
-try {
-  await import(pathToFileURL(bundledPostinstallPath).href);
-} catch (error) {
-  if (!(error && typeof error === "object" && error.code === "ENOENT")) {
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`[clawdentity] postinstall failed: ${message}\n`);
-    process.exitCode = 1;
+if (existsSync(bundledPostinstallPath)) {
+  try {
+    await import(pathToFileURL(bundledPostinstallPath).href);
+  } catch (error) {
+    if (
+      !(
+        error &&
+        typeof error === "object" &&
+        (error.code === "ENOENT" || error.code === "ERR_MODULE_NOT_FOUND")
+      )
+    ) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`[clawdentity] postinstall failed: ${message}\n`);
+      process.exitCode = 1;
+    }
   }
 }

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

@@ -16,6 +16,30 @@ After setup, this skill also covers lifecycle operations: token refresh, API key
 
 Relay invite codes are not part of this flow.
 
+## State Discovery First (required before asking for onboarding inputs)
+
+Always detect existing local state before asking for invite code, API key, or peer setup.
+
+1. Resolve OpenClaw state root.
+- Default: `~/.openclaw`
+- Respect env overrides: `OPENCLAW_STATE_DIR`, legacy `CLAWDBOT_STATE_DIR`, `OPENCLAW_HOME`
+
+2. Resolve Clawdentity state root using this order.
+- Primary: `~/.clawdentity`
+- Fallback: `<openclaw-state>/.clawdentity`
+
+3. If fallback exists and primary is missing:
+- Run all `clawdentity ...` commands with `HOME=<openclaw-state>` so CLI resolves the same state root as OpenClaw profile.
+
+4. Run readiness probe before asking questions:
+- `clawdentity openclaw doctor --json`
+
+5. Behavior gate from doctor output:
+- If doctor is healthy: do not ask for onboarding invite/API key; proceed directly with requested relay/pairing action.
+- If doctor is unhealthy: ask only for the minimum missing input required by failed checks.
+
+Never claim that no local relay setup exists until this discovery flow is complete.
+
 ## Filesystem Truth (must be used exactly)
 
 ### OpenClaw state files
@@ -139,10 +163,13 @@ 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>`
@@ -176,9 +203,10 @@ Use `--no-runtime-start` when the connector runs as a separate container or proc
   - `npm install -g clawdentity@latest`
 - Confirm local agent name.
 - Confirm local human display name for onboarding.
-- Check local API key status with `clawdentity config get apiKey`.
-- If API key is missing, ask for onboarding invite `clw_inv_...` and continue with invite redeem.
-- Do not ask for raw API key unless the user explicitly says invite is unavailable.
+- Check existing relay state first using **State Discovery First** above.
+- Check local API key status with `clawdentity config get apiKey` only after state root resolution is confirmed.
+- If API key is missing and doctor indicates onboarding is incomplete, ask for onboarding invite `clw_inv_...` and continue with invite redeem.
+- Do not ask for raw API key unless the user explicitly says invite is unavailable and onboarding invite cannot be provided.
 - Confirm OpenClaw path/base URL only if non-default.
 - Do not ask for pairing inputs before onboarding is complete.
 
@@ -256,7 +284,11 @@ 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.
-- 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.
+- 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`
 - Confirm pairing success, then run `clawdentity openclaw relay test`.
 - **Validate:** `~/.clawdentity/peers.json` contains the new peer alias entry.
 
@@ -274,26 +306,38 @@ Use `--no-runtime-start` when the connector runs as a separate container or proc
 After pairing, agents receive relayed messages from their paired peers.
 Identity injection is enabled by default (`INJECT_IDENTITY_INTO_MESSAGE=true` on proxy).
 
+**Do not reply to peer messages in chat.** Chat replies stay local and never reach the peer. All replies to a peer must be sent via the relay webhook with `"peer": "<alias>"` in the payload.
+
 ### Recognizing incoming messages
 - Relayed messages contain a `[Clawdentity Identity]` block prepended to the message body.
 - Extract `agentDid` from this block to identify the sender.
 - See `references/clawdentity-protocol.md` § Identity Injection for the exact block format and field definitions.
 - The connector `deliver` frame also exposes `fromAgentDid` for programmatic access.
+- When you see a `[Clawdentity Identity]` block, the message is from a peer. Do not answer in chat. Follow the reply flow below.
 
 ### Looking up peer identity
 - Map sender `agentDid` to a known peer by matching against `did` in `~/.clawdentity/peers.json`.
 - Each peer entry contains:
   - `did` — the peer's agent DID (match key)
-  - `agentName` — the peer's agent name (use for addressing)
-  - `humanName` — the human behind the peer agent (use for context)
+  - `agentName` — the peer's agent name
+  - `humanName` — the human behind the peer agent
   - `proxyUrl` — the peer's proxy endpoint
-- Address the peer by `agentName` or `humanName` in responses for natural conversation.
+- The peer alias is the key of that entry in `peers.json` (e.g., `"beta"`). Use this alias in the reply payload.
 
 ### Sending messages to a peer
+This is the only way to reply to a peer or send a new message. Chat replies do not reach peers.
 - Include `"peer": "<alias>"` in the webhook payload to route via relay.
-- The alias is the key in `peers.json` (e.g., `"beta"`).
+- Use the alias resolved from the lookup step above.
+- Use `agentName` or `humanName` in the message text for natural addressing.
 - The relay transform strips `peer` from the payload and routes to the connector.
 
+### Reply flow
+When a relayed peer message arrives:
+1. Extract `agentDid` from the `[Clawdentity Identity]` block.
+2. Look up the peer alias by matching `agentDid` against `did` in `~/.clawdentity/peers.json`.
+3. Compose a webhook payload with `"peer": "<alias>"` set to the resolved alias.
+4. The relay delivers the payload to the peer. Do not also reply in chat.
+
 ### Peer validation
 - `clawdentity openclaw doctor --peer <alias>` confirms a specific peer is reachable.
 - `clawdentity openclaw relay test --peer <alias>` sends a test probe to the peer.
@@ -356,7 +400,10 @@ 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.
-- `CLI_PAIR_STATUS_WAIT_TIMEOUT`: responder did not confirm in time. Re-run `pair start`.
+- `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_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_...>`.
 - Responder shows peer but initiator does not:

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

@@ -21,6 +21,19 @@ Complete reference for CLI environment variable overrides. When env overrides ar
 | `OPENCLAW_STATE_DIR` | Override OpenClaw state directory | openclaw |
 | `OPENCLAW_HOME` | Override OpenClaw home directory (used when explicit config/state overrides are unset) | openclaw |
 
+## Profile-Local State Resolution
+
+In profile-mounted/containerized OpenClaw environments, Clawdentity state may be stored at:
+- `<openclaw-state>/.clawdentity`
+
+instead of:
+- `~/.clawdentity`
+
+If `~/.clawdentity` is missing but `<openclaw-state>/.clawdentity` exists, run CLI commands with:
+- `HOME=<openclaw-state>`
+
+This makes `clawdentity` resolve the correct profile-local state root.
+
 ## Legacy Environment Variables
 
 | Variable | Replaced By |

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Ravi Kiran Vemula
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.