@waiaas/skills 2.7.0 → 2.8.0-rc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waiaas/skills",
-  "version": "2.7.0",
+  "version": "2.8.0-rc",
   "description": "WAIaaS skill files for AI agents - install via npx @waiaas/skills add <name>",
   "license": "MIT",
   "type": "module",

package/skills/actions.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Actions"
 description: "Action Provider framework: list providers, execute DeFi actions through the 6-stage transaction pipeline"
 category: "api"
 tags: [wallet, blockchain, defi, actions, waiass, jupiter, 0x, swap, lifi, bridge, cross-chain, lido, jito, staking, liquid-staking]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/admin.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Admin"
 description: "Admin API: daemon status, kill switch, notifications, settings management, JWT rotation, shutdown, oracle status, API key management"
 category: "api"
 tags: [wallet, blockchain, admin, security, oracle, defi, waiass]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/policies.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Policies"
 description: "Policy engine CRUD: 12 policy types for spending limits, whitelists, time restrictions, rate limits, token/contract/approve controls, network restrictions, x402 domain controls"
 category: "api"
 tags: [wallet, blockchain, policies, security, waiass]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/quickstart.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Quickset"
 description: "End-to-end quickset: create wallet, session, check balance, send first transfer"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, quickset, quickstart, waiass]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/session-recovery.skill.md

@@ -0,0 +1,112 @@
+---
+name: "WAIaaS Session Recovery"
+description: "Recover from expired or permanently expired session tokens"
+category: "api"
+tags: [wallet, blockchain, session, recovery, token, expired, waiass]
+version: "2.8.0-rc"
+dispatch:
+  kind: "tool"
+  allowedCommands: ["curl"]
+---
+
+# WAIaaS Session Recovery
+
+This skill guides you through recovering from an expired session token. Follow the appropriate path based on your error type.
+
+> AI agents must NEVER request the master password. Use only your session token.
+
+## Diagnosing the Problem
+
+When you receive a `401` response with one of these error codes, your session needs attention:
+
+| Error Code | Meaning | Recovery Path |
+|-----------|---------|---------------|
+| `TOKEN_EXPIRED` | Session TTL elapsed | Try renewal first |
+| `RENEWAL_LIMIT_REACHED` | Max renewals exceeded (default 12) | Request new session |
+| `SESSION_REVOKED` | Session manually revoked by operator | Request new session |
+| `SESSION_NOT_FOUND` | Session deleted or invalid | Request new session |
+
+## Path A: Session Renewal (Self-Service)
+
+If your session is expired but not permanently, try renewing it first:
+
+```bash
+curl -s -X PUT http://localhost:3100/v1/sessions/{sessionId}/renew \
+  -H "Authorization: Bearer wai_sess_..." | jq .
+```
+
+**Success response:**
+```json
+{
+  "token": "wai_sess_<new-token>",
+  "expiresAt": 1740000000,
+  "renewalCount": 1
+}
+```
+
+Update your session token with the new value and continue operating.
+
+**Safety checks that may block renewal:**
+- Less than 50% of TTL has elapsed (too early)
+- Renewal count exceeds max (default 12)
+- Absolute session lifetime exceeded (default 1 year)
+- Token hash mismatch (concurrent renewal detected)
+
+## Path B: Request New Session from Operator
+
+When renewal is not possible (RENEWAL_LIMIT_REACHED, SESSION_REVOKED, SESSION_NOT_FOUND), you cannot self-recover. Follow these steps:
+
+### Step 1: Inform the User
+
+Tell the user clearly:
+
+> My WAIaaS session token has permanently expired and cannot be renewed. I need a new session token to continue operating.
+
+### Step 2: Guide the Operator
+
+The operator (human user) should create a new session via one of these methods:
+
+**Option A: CLI (recommended)**
+```bash
+waiaas session prompt
+```
+This generates a new session with an AI-ready connection prompt.
+
+**Option B: Admin UI**
+1. Open Admin UI (http://localhost:3100/admin)
+2. Navigate to Sessions page
+3. Click "Create Session" and select the wallets
+4. Copy the generated token
+
+**Option C: REST API**
+```bash
+curl -s -X POST http://localhost:3100/v1/sessions \
+  -H "Content-Type: application/json" \
+  -H "X-Master-Password: <operator-enters-password>" \
+  -d '{"walletIds": ["<wallet-id>"], "ttl": 2592000}' | jq .
+```
+
+### Step 3: Apply the New Token
+
+Once the operator provides the new token:
+
+**For MCP agents:** The operator updates the token file at `DATA_DIR/mcp-token`. The MCP recovery loop polls this file every 60 seconds and will automatically pick up the new token.
+
+**For REST API agents:** Update the `Authorization: Bearer wai_sess_...` header with the new token value.
+
+### Step 4: Verify Recovery
+
+After applying the new token, call connect-info to verify:
+
+```bash
+curl -s http://localhost:3100/v1/connect-info \
+  -H "Authorization: Bearer wai_sess_<new-token>" | jq .session
+```
+
+Expected: 200 OK with session info including new `expiresAt`.
+
+## Prevention Tips
+
+- **Check session expiry proactively**: The `connect-info` response includes `session.expiresAt` (Unix timestamp). Monitor this to renew before expiration.
+- **Renew early**: Call `PUT /v1/sessions/{id}/renew` when 60% of TTL has elapsed (MCP agents do this automatically).
+- **Use long TTL**: Default session TTL is 30 days. The operator can configure up to 1 year via Admin Settings.

package/skills/setup.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Setup"
 description: "Zero-state daemon setup: install CLI, initialize, start daemon, create wallet, configure session"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, setup, install, waiass]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl", "npm", "npx", "waiaas", "which"]

package/skills/transactions.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Transactions"
 description: "All 5 transaction types (TRANSFER, TOKEN_TRANSFER, CONTRACT_CALL, APPROVE, BATCH) with lifecycle management"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, transactions, waiass]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/wallet.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Wallet Management"
 description: "Wallet CRUD, asset queries, session management, token registry, MCP provisioning, owner management"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, sessions, tokens, mcp, waiass]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -176,6 +176,15 @@ curl -s -X PUT http://localhost:3100/v1/wallets/01958f3a-1234-7000-8000-abcdef12
 Parameters:
 - `owner_address` (required): blockchain address (Solana base58 or Ethereum 0x-prefixed, EIP-55 normalized)
 - `approval_method` (optional): Owner approval method override for this wallet. Valid values: `"sdk_ntfy"`, `"sdk_telegram"`, `"walletconnect"`, `"telegram_bot"`, `"rest"`, or `null` (auto-detect). Set to `null` to clear and use automatic channel detection.
+- `wallet_type` (optional): Built-in wallet preset type. Valid values: `"dcent"`. When specified, the preset's approval_method and preferred_wallet override manual settings.
+
+```bash
+# With wallet preset:
+curl -s -X PUT http://localhost:3100/v1/wallets/01958f3a-1234-7000-8000-abcdef123456/owner \
+  -H 'Content-Type: application/json' \
+  -H 'X-Master-Password: your-master-password' \
+  -d '{"owner_address": "0x1234...abcd", "wallet_type": "dcent"}'
+```
 
 Response (200):
 ```json
@@ -190,10 +199,14 @@ Response (200):
   "ownerAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
   "ownerVerified": false,
   "approvalMethod": null,
+  "walletType": null,
+  "warning": null,
   "updatedAt": 1707000100
 }
 ```
 
+When both `wallet_type` and `approval_method` are provided, the preset's approval_method takes precedence and a `warning` field is included in the response.
+
 Error: `OWNER_ALREADY_CONNECTED` (409) if wallet is in LOCKED state -- use ownerAuth to change owner.
 
 ### POST /v1/wallets/{id}/owner/verify -- Verify Owner Signature (masterAuth + ownerAuth)

package/skills/x402.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS x402"
 description: "x402 auto-payment protocol: fetch URLs with automatic cryptocurrency payments"
 category: "api"
 tags: [wallet, blockchain, x402, payments, waiass]
-version: "2.7.0"
+version: "2.8.0-rc"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]