@aeon-ai-pay/aigateway 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.3] — 2026-05-19
+
+### Fixed
+- **`wallet-init` no longer requires `mainWallet` field in config to consider the wallet "funded".**
+  Previously the decision tree was `created || !config.mainWallet ⇒ needsTopup=true`, which meant
+  a session wallet that had USDT and was already approved on-chain — but whose local config had
+  never recorded a `mainWallet` (e.g. funded by an external CEX transfer, or copied from another
+  machine without that field) — would still be flagged as needing a top-up, sending the agent
+  through a redundant `wallet-topup` flow. The decision now relies only on on-chain state
+  (USDT balance ≥ `LOW_BALANCE_THRESHOLD` and `allowance > 0`). `mainWallet` is treated purely
+  as a withdraw-default and has no effect on `needsTopup`.
+- `topupReason` enum updated: `no_prior_funding` removed; new values are `first_time` (replaces
+  the created branch), `low_balance`, `no_approve`, and `chain_check_failed`.
+
+## [0.1.2] — 2026-05-19
+
+### Changed
+- **SKILL.md wording discipline**: `wallet-topup` ask and `create-card` ask now have
+  enforced lexical separation. Step 2 (`wallet-topup`) explicitly says "load USDT
+  **into your session wallet**" / "往**本地钱包**充值 USDT". Step 3a (`create-card`)
+  says "card **face value**" / "**开多少美元的卡** / 卡的面额", and explicitly
+  forbids translating it as "充值". Fixes a UX confusion where a user with a
+  funded wallet would be asked "请问您想充值多少美元到虚拟卡上?" and reasonably
+  wonder if it was another wallet top-up prompt.
+- New "Wording Discipline" section in SKILL.md `## Copy Constraints` to lock this in.
+
+## [0.1.1] — 2026-05-19
+
+### Changed
+- **`wallet-init` now reports full funding status**, not just local-key readiness. Envelope `data` adds:
+  `usdt`, `bnb`, `allowance`, `needsTopup`, `topupReason` (`no_prior_funding` / `low_balance` / `no_approve`),
+  `minTopup`, `presets`, `chainCheck`. Agents can decide the next step (`wallet-topup` vs. go straight to a paid
+  call) from this single envelope without a separate `wallet-balance` call.
+- **SKILL.md workflow re-ordered** so agents prompt the user for a top-up amount **before** invoking the first
+  paid command, eliminating the previous "try-create-card → fail with `TOPUP_REQUIRED` → ask amount" UX bug.
+- SKILL.md adds an "If `aigateway` is not found (exit 127)" fallback that instructs the agent to run
+  `npm install -g @aeon-ai-pay/aigateway` once and retry.
+
 ## [0.1.0] — 2026-05-18
 
 Initial release of **AEON AI Gateway**, merging the prior `@aeon-ai-pay/aicard` and `@aeon-ai-pay/agentos` projects into a single unified CLI and agent skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeon-ai-pay/aigateway",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "AI Agents discover, invoke, and settle paid LLMs, APIs, and Skills — starting with Skill Boss. No manual key setup. No prepayment. Pay-per-call via x402 or Agent Card.",
   "type": "module",
   "bin": {

package/skills/aigateway/SKILL.md

@@ -16,7 +16,7 @@ description: >
 emoji: "🛰️"
 homepage: https://github.com/AEON-Project/aigateway
 metadata:
-  version: "0.1.0"
+  version: "0.1.3"
   author: AEON-Project
   openclaw:
     requires:
@@ -73,13 +73,13 @@ See [docs/output-schema.md](../../docs/output-schema.md) and [docs/exit-codes.md
 ## Command Overview
 
 ```bash
-aigateway wallet-init                             # Pre-check / auto-create local session wallet (no QR)
+aigateway wallet-init                             # Pre-check / create wallet AND report needsTopup status (one-stop pre-flight)
 aigateway wallet-topup [--amount <usdt>]          # WalletConnect: top-up USDT (≥5; presets 5/10/20/50) + first-time facilitator approve
 aigateway create-card --amount <usd> --poll       # Issue a virtual card ($0.6 ~ $800)
 aigateway create-image --prompt "<text>"          # Generate AI image
 aigateway create-card-status --order-no <orderNo> [--poll]    # Query card status
-aigateway wallet-balance                          # Check local wallet balance
-aigateway wallet-gas [--amount <bnb>]                    # Top up BNB for session key (for withdraw)
+aigateway wallet-balance                          # (optional) Re-query balance — agent rarely needs this; wallet-init already reports it
+aigateway wallet-gas [--amount <bnb>]             # Top up BNB for session key (for withdraw)
 aigateway wallet-withdraw [--to <addr>] [--amount <usdt>]   # Reclaim funds
 aigateway clean                                   # Uninstall skill, clear cache
 ```
@@ -104,33 +104,76 @@ Output template:
 > Pre-check in progress...
 ```
 
-`envelope.data`: `{ ready, created, mode, address, mainWallet, serviceUrl, amountLimits }`.
+### If `aigateway` is not found (exit 127 / "command not found")
 
-- `created: true` → "Auto-creating your designated wallet..." + then "0x0...{last4} Ready."
-- `created: false`, `ready: true` → "0x0...{last4} Ready."
-- Record `amountLimits.{min,max}` for any subsequent card amount validation.
+The CLI hasn't been installed on this host yet. Output to the user **verbatim**:
 
----
-
-## Step 2: Top up (First-Time Funding + Approve)
+```
+> Installing aigateway...
+```
 
-Trigger: any of (first paid call) | (`wallet-balance` shows < 1 USDT) | (user explicitly wants to "top up" / "load wallet" / "add funds").
+Then run **in the foreground** (this can take 30–60 seconds; do **not** background it):
 
 ```bash
-aigateway wallet-topup                            # Interactive top-up amount prompt (TTY only)
-aigateway wallet-topup --amount 5                 # Non-interactive (recommended for agent invocations)
+npm install -g @aeon-ai-pay/aigateway
+```
+
+After install completes, re-run `aigateway wallet-init`. If `npm install` itself fails (network / permissions), surface the raw error and ask the user to fix their npm environment.
+
+### Envelope on success
+
+`envelope.data` (full shape):
+
+```json
+{
+  "ready": true,
+  "created": false,
+  "address": "0x...",
+  "mainWallet": "0x..." | null,
+  "usdt": "5.0",
+  "bnb": "0.0003",
+  "allowance": "115792...max" | "0",
+  "needsTopup": false,
+  "topupReason": null | "no_prior_funding" | "low_balance" | "no_approve",
+  "minTopup": 5,
+  "presets": [5, 10, 20, 50],
+  "amountLimits": { "min": 0.6, "max": 800 }
+}
 ```
 
-### When does topup do nothing?
+### Decision tree (this is the whole pre-flight)
+
+| Field | Action |
+| --- | --- |
+| `created: true` | "Auto-creating your designated wallet..." + "0x0...{last4} Ready." |
+| `created: false`, `ready: true` | "0x0...{last4} Ready." |
+| **`needsTopup: true`** | **Go to Step 2 immediately.** Use `presets` / `minTopup` from this envelope (don't hardcode). |
+| `needsTopup: false` | Wallet has enough USDT and is approved. **Skip Step 2** and jump straight to the user's intent (`create-card` / `create-image` / other). |
+
+Record `amountLimits.{min,max}` for any subsequent card amount validation.
+
+---
+
+## Step 2: Top up (only if Step 1's envelope says `needsTopup: true`)
 
-If `wallet` shows USDT ≥ 1 **and** allowance is already non-zero **and** the user did not explicitly ask to add funds, skip Step 2 entirely.
+Trigger: `wallet-init` envelope reports `needsTopup: true` (any of `no_prior_funding` / `low_balance` / `no_approve`), **or** the user explicitly asks to top up / load funds.
 
 ### Amount selection
 
+This is a **session-wallet top-up** in USDT (NOT card face value). Make the wording unambiguously about the wallet to avoid the user confusing it with the card face value asked in Step 3a.
+
 - Presets: **5 / 10 / 20 / 50 USDT**. Custom amounts must be ≥ 5 USDT.
-- If user said "top up" without an amount, use this exact copy and ask:
-  > How much USDT would you like to load? (presets: 5 / 10 / 20 / 50, or any custom amount ≥ 5)
-- Once the user picks an amount, run with `--amount <n>`.
+- Ask the user **before** running the command. **Make "wallet" / "钱包" explicit in the question:**
+
+  > How much USDT would you like to load **into your session wallet**? (presets: 5 / 10 / 20 / 50, or any custom amount ≥ 5)
+
+  (Suggested Chinese phrasing: "请问要往**本地钱包**充值多少 USDT？预设 5 / 10 / 20 / 50，或自定义 ≥ 5。")
+
+- Once the user picks an amount, run:
+
+```bash
+aigateway wallet-topup --amount <n>     # always pass --amount in agent context
+```
 
 ### Output template
 
@@ -151,8 +194,8 @@ Approve:   {approveTx truncated or "already approved"}
 
 | `error.code` | Action |
 | --- | --- |
-| `TOPUP_REQUIRED` (non-TTY, balance < 1 USDT) | Ask user for amount (presets in `error.presets`), then rerun with `--amount <n>`. |
-| `TOPUP_AMOUNT_TOO_SMALL` | Show `error.minTopup`, ask again. |
+| `TOPUP_REQUIRED` (would only happen if you skipped Step 2) | Bug in agent — should have asked for amount in Step 3. Ask now, then rerun with `--amount <n>`. |
+| `TOPUP_AMOUNT_TOO_SMALL` | Show `error.minTopup`, ask the user for a larger amount. |
 | `PAYMENT_REJECTED` | User cancelled in wallet. **Do not auto-retry**; ask user. |
 | `PAYMENT_TIMEOUT` | 5-minute WalletConnect window expired. **Do not auto-retry**; ask user. |
 | `INSUFFICIENT_BNB` (post-funding) | Run `aigateway wallet-gas` (interactive) to add BNB, then retry. |
@@ -164,13 +207,16 @@ Approve:   {approveTx truncated or "already approved"}
 
 ## Step 3a: Create Virtual Card
 
-Trigger: user wants to **buy / create / get a virtual card**.
+Trigger: user wants to **buy / create / get a virtual card** *and* Step 1 envelope showed `needsTopup: false` (or Step 2 just completed successfully).
 
 ### Amount confirmation
 
-Amount must be in `amountLimits.min ~ amountLimits.max` (from Step 1; never hardcode). If user did not specify, ask once:
+This is the **card face value** the user wants to issue (NOT a wallet top-up). Amount must be in `amountLimits.min ~ amountLimits.max` (from Step 1; never hardcode). If user did not specify, ask once — **use the word "card face value" / "面额", never "充值" / "top up"** to avoid confusing it with the `wallet-topup` step:
+
+> What card face value would you like to issue? Allowed range: ${min}~${max} USD.
 
-> You can create a card of up to ${min}~${max}. How much would you like to load onto the card?
+(Suggested Chinese phrasing: "请问要开多少美元的卡？允许范围 $${min} ~ $${max}。"
+**Do not** translate this as "充值多少美元" — that wording belongs to `wallet-topup` and confuses users.)
 
 Once specified, **execute immediately**.
 
@@ -368,3 +414,14 @@ The following first-line / key-phrase strings must be **exactly reproduced** —
 | Wallet prepared header | `✅ Wallet prepared` |
 
 Address rendering: always `0x0...{last4}` (first 3 + ellipsis + last 4 chars).
+
+### Wording Discipline: "wallet top-up" vs "card face value"
+
+These two amounts are **different concepts** asked at **different steps**. Translators must keep them lexically distinct so users don't conflate them:
+
+| Step | Concept | Required wording (English) | Suggested Chinese | Forbidden mix-ups |
+| --- | --- | --- | --- | --- |
+| Step 2 (`wallet-topup`) | USDT into the **session wallet** | "load USDT **into your session wallet**" | "往**本地钱包**充值 USDT" | Don't say "充值到卡里" / "load onto the card" — that's Step 3a |
+| Step 3a (`create-card`) | USD **face value** loaded onto a new card | "card **face value**" / "issue a card with how much" | "**开多少美元的卡** / 卡的面额" | Don't say "充值多少" / "充值到卡" without strong "card" qualifier — confuses with Step 2 |
+
+**Rule of thumb**: if the agent's question contains the word "充值" (top up), the noun *must* be "钱包" (wallet); if the question is about a card's amount, prefer "**面额**" or "**开多少美元的卡**", never "充值".

package/src/commands/wallet-init.mjs

@@ -1,15 +1,26 @@
 /**
- * init-wallet：本地 session 钱包 check / 创建
+ * wallet-init：本地 session 钱包 check / 创建 + 链上状态评估
  *
- * 纯本地操作 —— 不上链、不扫码、不花钱。
- *   - 如果 ~/.aigateway/config.json 没有 privateKey → 用 viem.generatePrivateKey() 生成一对
- *   - 返回当前钱包就绪状态（ready / created / address / amountLimits / ...）
+ * 步骤：
+ *   1. 若 ~/.aigateway/config.json 缺 privateKey → 用 viem.generatePrivateKey() 生成
+ *   2. 查 USDT / BNB 余额（除非刚 created，则跳过查询直接判定为 needsTopup）
+ *   3. 查 facilitator allowance（同上规则）
+ *   4. 综合判定 needsTopup 与原因，返回完整就绪状态供 agent 决策
  *
- * Agent 任何入口的第一步都应该先跑这个确认环境就绪。再之后才是 topup（充值）/ create-* 等需要钱的命令。
+ * 设计意图：agent 跑完 wallet-init 一条命令就拿到决策依据：
+ *   - data.ready=true 表示钱包私钥可用
+ *   - data.needsTopup=true → 必须先 wallet-topup（envelope 里附带 presets / minTopup / reason）
+ *   - data.needsTopup=false → 可直接 create-card / create-image
  */
 import { loadConfig, saveConfig } from "../config.mjs";
 import { MIN_AMOUNT, MAX_AMOUNT } from "../constants.mjs";
-import { emitOk } from "../output.mjs";
+import { getWalletBalance, getAllowance } from "../balance.mjs";
+import {
+  LOW_BALANCE_THRESHOLD,
+  MIN_TOPUP_USDT,
+  TOPUP_PRESETS,
+} from "../funding.mjs";
+import { emitOk, logInfo } from "../output.mjs";
 
 export async function initWallet(opts) {
   const config = loadConfig();
@@ -25,18 +36,77 @@ export async function initWallet(opts) {
     config.mode = "private-key";
     created = true;
     saveConfig(config);
+    logInfo(`Auto-created session wallet: ${config.address}`);
+  } else {
+    logInfo(`Wallet: ${config.address}`);
+  }
+
+  // 链上状态评估
+  let usdt = "0";
+  let bnb = "0";
+  let usdtNum = 0;
+  let allowance = 0n;
+  let chainCheckOk = true;
+  let chainCheckError = null;
+
+  if (created) {
+    // 刚建好的钱包余额必然为 0，跳过链上查询节省 ~500ms
+    logInfo("Fresh wallet — skipping balance lookup (assumed empty).");
+  } else {
+    try {
+      const bal = await getWalletBalance(config.privateKey);
+      usdt = bal.usdt;
+      bnb = bal.bnb;
+      usdtNum = parseFloat(usdt);
+      logInfo(`Balance: ${usdt} USDT, ${bnb} BNB`);
+      allowance = await getAllowance(config.address);
+      logInfo(`Allowance: ${allowance === 0n ? "0 (approve required)" : "already approved"}`);
+    } catch (e) {
+      chainCheckOk = false;
+      chainCheckError = e.message;
+      logInfo(`Chain status check failed: ${e.message}`);
+    }
+  }
+
+  // 决策：是否需要 topup —— 只看链上真实状态，不依赖 config.mainWallet 字段。
+  // 之前用 !config.mainWallet 当判断条件是错的：mainWallet 只是 withdraw 默认目标地址，
+  // 即使为 null（如用户外部转账 / 旧版本未记录），只要链上 USDT/allowance 充足就应该
+  // 直接允许付费调用，不要强制再走一次 wallet-topup。
+  let needsTopup = false;
+  let topupReason = null;
+  if (created) {
+    // 刚生成的 session key 必然没钱，无需查链
+    needsTopup = true;
+    topupReason = "first_time";
+  } else if (!chainCheckOk) {
+    // 链上查询失败 —— 保守标记需要 topup 由用户决定下一步
+    needsTopup = true;
+    topupReason = "chain_check_failed";
+  } else if (usdtNum < LOW_BALANCE_THRESHOLD) {
+    needsTopup = true;
+    topupReason = "low_balance";
+  } else if (allowance === 0n) {
+    needsTopup = true;
+    topupReason = "no_approve";
   }
 
-  const ready = !!(config.serviceUrl && config.privateKey);
   const data = {
-    ready,
+    ready: true,
     created,
     appId,
     mode: config.mode || null,
     address: config.address || null,
     mainWallet: config.mainWallet || null,
     serviceUrl: config.serviceUrl || null,
+    usdt,
+    bnb,
+    allowance: allowance.toString(),
+    needsTopup,
+    topupReason,            // "no_prior_funding" | "low_balance" | "no_approve" | null
+    minTopup: MIN_TOPUP_USDT,
+    presets: TOPUP_PRESETS,
     amountLimits: { min: MIN_AMOUNT, max: MAX_AMOUNT },
+    chainCheck: chainCheckOk ? "ok" : { error: chainCheckError },
   };
   emitOk("wallet-init", data, data);
 }