@aeon-ai-pay/aigateway 0.1.1 → 0.1.4

package/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.4] — 2026-05-19
+
+### Added
+- **`create-card` envelope now carries a `balance` block** (`initial`, `before`,
+  `after`, `charged`, `topup`) parallel to `create-image`, so the agent can
+  render the same money-flow narrative for card issuance.
+
+### Changed
+- **Both paid commands adopt an emoji-aligned card-style success template**
+  with explicit balance transitions (`{initial} → {before}` for top-up;
+  `{before} → {after}` for charge) on dedicated rows. The `💸 Top-up` row is
+  conditional — only rendered when `balance.topup` is non-null.
+  - `create-card`: header `✅ Card Issued`, rows for Order / Card / State /
+    Face value / Usage / Tx / (optional) Top-up / Charged.
+  - `create-image`: header `✅ Generated`, second row `🧩 Powered by Skillboss`,
+    rows for Path / Format / Dimensions / Size / Tx / (optional) Top-up /
+    Charged.
+- SKILL.md Copy Constraints table extended with all new template rows so
+  agents must reproduce the glyphs (`→`, `−`, `+`) exactly.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeon-ai-pay/aigateway",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "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.1"
+  version: "0.1.4"
   author: AEON-Project
   openclaw:
     requires:
@@ -160,9 +160,15 @@ Trigger: `wallet-init` envelope reports `needsTopup: true` (any of `no_prior_fun
 
 ### 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.
-- Ask the user **before** running the command:
-  > How much USDT would you like to load? (presets: 5 / 10 / 20 / 50, or any custom amount ≥ 5)
+- 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
@@ -205,9 +211,12 @@ Trigger: user wants to **buy / create / get a virtual card** *and* Step 1 envelo
 
 ### 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:
 
-> You can create a card of up to ${min}~${max}. How much would you like to load onto the card?
+> What card face value would you like to issue? Allowed range: ${min}~${max} USD.
+
+(Suggested Chinese phrasing: "请问要开多少美元的卡？允许范围 $${min} ~ $${max}。"
+**Do not** translate this as "充值多少美元" — that wording belongs to `wallet-topup` and confuses users.)
 
 Once specified, **execute immediately**.
 
@@ -229,16 +238,30 @@ Output template first line:
 
 ### Success
 
-`envelope.data`: `{ orderNo, data, paymentResponse, pollResult? }`. After fetching details (may take ~30 s), display **verbatim**:
+`envelope.data`: `{ orderNo, amount, data, paymentResponse, balance: { initial, before, after, charged, topup }, pollResult? }`.
+
+After fetching details (may take ~30 s), display **verbatim** (emoji, spacing, glyphs `→` / `−` / `+` must match exactly):
 
 ```
-Order No: {orderNo}
-Card: {cardScheme} •••• {last4}
-State: Active
-Remaining balance: ${amount} USD
-Usage: 0 / 1 (single-use)
+✅ Card Issued
+🆔 Order        {orderNo}
+💳 Card         {cardScheme} •••• {last4}
+🎯 State        Active
+💵 Face value   ${amount} USD
+🔢 Usage        0 / 1 (single-use)
+🔗 Tx           {transaction}
+💸 Top-up       {initial} → {before} USDT (+{topup})
+💰 Charged      {before} → {after} USDT (−{charged})
 ```
 
+**Field rules:**
+
+- `{cardScheme}` and `••••{last4}` come from `data.data.model` (already sanitized — never show full card number).
+- `{transaction}` is `data.paymentResponse.txHash` or `data.data.transaction`. If absent, render the line as `🔗 Tx           —`.
+- The **`💸 Top-up`** row is **conditional**: render only when `data.balance.topup` is non-null and non-zero (i.e. a lazy top-up actually happened during this call). Otherwise **omit the entire `💸 Top-up` line**.
+- The **`💰 Charged`** row is always rendered.
+- Use the minus sign character `−` (U+2212) before `{charged}`, not the hyphen `-`. Use `→` (U+2192) for the balance transition arrow.
+
 Always record `orderNo` — only identifier for status queries.
 
 ### Errors
@@ -275,19 +298,31 @@ Output template first line:
 
 ### Success
 
-`envelope.data`: `{ prompt, transaction, images: [{ url, localPath, format, width, height, sizeHuman }], balance: { initial, before, after, charged } }`.
+`envelope.data`: `{ prompt, transaction, images: [{ url, localPath, format, width, height, sizeHuman }], balance: { initial, before, after, charged, topup } }`.
 
-Display **verbatim**:
+Display **verbatim** (emoji, spacing, dash glyphs `→` / `−` / `+` must match exactly):
 
 ```
 ✅ Generated
-Prompt:       {prompt}
-Image:        {localPath} ({width}×{height}, {sizeHuman})
-Transaction:  {transaction}
-Charged:      {balance.charged} USDT
-Balance:      {balance.after} USDT remaining
+🧩 Powered by Skillboss
+📁 Path        {localPath}
+🎨 Format      {FORMAT}
+📐 Dimensions  {width} × {height}
+💾 Size        {sizeHuman}
+🔗 Tx          {transaction}
+💸 Top-up      {initial} → {before} USDT (+{topup})
+💰 Charged     {before} → {after} USDT (−{charged})
 ```
 
+**Field rules:**
+
+- `{FORMAT}` is `data.outputFormat` uppercased (e.g. `PNG`, `JPEG`, `WEBP`).
+- `{width}` / `{height}` / `{sizeHuman}` come from `data.images[0]` (first image only — agent does not list extras unless asked).
+- `{transaction}` is `data.transaction` (may be `null` if the server didn't return one; in that case render the line as `🔗 Tx          —`).
+- The **`💸 Top-up`** line is **conditional**: only render it if `data.balance.topup` is not null and not "0" (i.e. a lazy top-up actually happened during this call). Otherwise **omit the entire `💸 Top-up` line**.
+- The **`💰 Charged`** line is always rendered.
+- Use the minus sign character `−` (U+2212) before `{charged}`, not the hyphen `-`. Use `→` (U+2192) for the balance transition arrow.
+
 ### Errors
 
 | `error.code` | Action |
@@ -395,6 +430,15 @@ The following first-line / key-phrase strings must be **exactly reproduced** —
 | Pre-check | `> Pre-check in progress...` |
 | Top up | `> Topping up wallet...` |
 | Create card | `> Creating Agent Card...` |
+| Card success header | `✅ Card Issued` |
+| Card Order row | `🆔 Order        {orderNo}` |
+| Card scheme row | `💳 Card         {cardScheme} •••• {last4}` |
+| Card State row | `🎯 State        Active` |
+| Card Face value row | `💵 Face value   ${amount} USD` |
+| Card Usage row | `🔢 Usage        0 / 1 (single-use)` |
+| Card Tx row | `🔗 Tx           {transaction}` |
+| Card Top-up row (conditional) | `💸 Top-up       {initial} → {before} USDT (+{topup})` |
+| Card Charged row | `💰 Charged      {before} → {after} USDT (−{charged})` |
 | Create image | `> Generating image...` |
 | Fetch details | `> Fetching card details, please wait...` |
 | Query status | `> Fetching card status...` |
@@ -402,6 +446,25 @@ The following first-line / key-phrase strings must be **exactly reproduced** —
 | Withdraw target line | `To: main wallet (0x0...{last4})` |
 | Withdraw status line | `Status: completed` |
 | Image success header | `✅ Generated` |
+| Image success row 2 | `🧩 Powered by Skillboss` |
+| Image Path row | `📁 Path        {localPath}` |
+| Image Format row | `🎨 Format      {FORMAT}` |
+| Image Dimensions row | `📐 Dimensions  {width} × {height}` |
+| Image Size row | `💾 Size        {sizeHuman}` |
+| Image Tx row | `🔗 Tx          {transaction}` |
+| Image Top-up row (conditional) | `💸 Top-up      {initial} → {before} USDT (+{topup})` |
+| Image Charged row | `💰 Charged     {before} → {after} USDT (−{charged})` |
 | 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/create-card.mjs

@@ -82,11 +82,13 @@ export async function createCard(opts) {
   let sessionAddress;
   let topupAmount = null;
   let balanceInitialUsdt = null;
+  let balanceBeforeChargeUsdt = null;
 
   try {
     const { address, usdt, bnb, bnbRaw } = await getWalletBalance(privateKey);
     sessionAddress = address;
     balanceInitialUsdt = usdt;
+    balanceBeforeChargeUsdt = usdt;
     const usdtNum = parseFloat(usdt);
     logInfo(`Wallet: ${address}`);
     logInfo(`Balance: ${usdt} USDT, ${bnb} BNB`);
@@ -210,6 +212,7 @@ export async function createCard(opts) {
     logInfo("Re-checking wallet balance...");
     try {
       const { usdt, bnbRaw } = await getWalletBalance(privateKey);
+      balanceBeforeChargeUsdt = usdt;
       const usdtNum = parseFloat(usdt);
       if (needGas && bnbRaw === 0n) {
         emitErr("create-card", "INSUFFICIENT_BNB", {
@@ -260,12 +263,28 @@ export async function createCard(opts) {
     const paymentResponse = decodePaymentResponse(response.headers);
     const orderNo = paymentReq.orderNo || response.data?.model?.orderNo || response.data?.orderNo;
 
+    let balanceAfterUsdt = null;
+    try {
+      const after = await getWalletBalance(privateKey);
+      balanceAfterUsdt = after.usdt;
+    } catch (e) {
+      logInfo(`Post-payment balance check failed: ${e.message}`);
+    }
+
     const sanitizedData = sanitizeOutput(response.data);
     const successData = {
       appId,
       orderNo,
+      amount,
       data: sanitizedData,
       paymentResponse,
+      balance: {
+        initial: balanceInitialUsdt,
+        before: balanceBeforeChargeUsdt,
+        after: balanceAfterUsdt,
+        charged: requiredUsdt,
+        topup: topupAmount,
+      },
     };
 
     function findCardStatus(obj) {

package/src/commands/wallet-init.mjs

@@ -68,16 +68,24 @@ export async function initWallet(opts) {
     }
   }
 
-  // 决策：是否需要 topup
+  // 决策：是否需要 topup —— 只看链上真实状态，不依赖 config.mainWallet 字段。
+  // 之前用 !config.mainWallet 当判断条件是错的：mainWallet 只是 withdraw 默认目标地址，
+  // 即使为 null（如用户外部转账 / 旧版本未记录），只要链上 USDT/allowance 充足就应该
+  // 直接允许付费调用，不要强制再走一次 wallet-topup。
   let needsTopup = false;
   let topupReason = null;
-  if (created || !config.mainWallet) {
+  if (created) {
+    // 刚生成的 session key 必然没钱，无需查链
+    needsTopup = true;
+    topupReason = "first_time";
+  } else if (!chainCheckOk) {
+    // 链上查询失败 —— 保守标记需要 topup 由用户决定下一步
     needsTopup = true;
-    topupReason = "no_prior_funding";
-  } else if (chainCheckOk && usdtNum < LOW_BALANCE_THRESHOLD) {
+    topupReason = "chain_check_failed";
+  } else if (usdtNum < LOW_BALANCE_THRESHOLD) {
     needsTopup = true;
     topupReason = "low_balance";
-  } else if (chainCheckOk && allowance === 0n) {
+  } else if (allowance === 0n) {
     needsTopup = true;
     topupReason = "no_approve";
   }