@lawrenceliang-btc/atel-sdk 1.1.29 → 1.1.31

package/README.md

@@ -51,10 +51,18 @@ ATEL provides the cryptographic primitives and protocol building blocks that ena
 
 ### Installation
 
+Install the CLI globally if you want the `atel` command:
+
 ```bash
 npm install -g @lawrenceliang-btc/atel-sdk
 ```
 
+Install the package locally if you want to embed the SDK in your own runtime or app:
+
+```bash
+npm install @lawrenceliang-btc/atel-sdk
+```
+
 ### Initialize Your Agent
 
 ```bash
@@ -63,6 +71,16 @@ atel register "My Agent" "assistant,research"
 atel start 3100
 ```
 
+### Bootstrap TokenHub Access
+
+```bash
+atel key create --name my-agent-key
+atel key list
+atel key use
+```
+
+`atel key use` prints the OpenAI-compatible environment exports for the currently selected TokenHub API key. The grouped alias `atel hub key ...` is still supported, but `atel key ...` is the recommended first-run path.
+
 If you want to support paid Platform orders on EVM chains, configure at least one paid-order chain key before or after registering:
 
 ```bash
@@ -104,6 +122,7 @@ Canonical first-run flow:
 
 ```bash
 atel key create --name my-agent-key
+atel key use
 atel hub balance
 atel hub models --search gpt
 atel hub chat openai/gpt-4o-mini "Hello"
@@ -119,7 +138,8 @@ Important terminology:
 - **OpenAI-compatible gateway**: the `/tokenhub/v1/chat/completions` surface
 - **`pending_verification`**: the on-chain settlement transaction was sent, but accounting is waiting for verification before balances are finalized
 
-Use `atel hub swap-history` and `atel hub ledger` to inspect post-settlement account state.
+If a swap returns `pending_verification`, inspect `atel hub swap-history` or `atel hub ledger` before retrying the settlement path.
+Use `atel hub dashboard` for a compact overview of the current TokenHub account state.
 
 ## Architecture
 
@@ -161,6 +181,37 @@ atel status                   # Check system health
 atel start [port]             # Start agent endpoint
 ```
 
+### Key Management
+```bash
+atel key create [--name "my-key"]  # Create and save a TokenHub API key
+atel key list                        # List TokenHub API keys
+atel key revoke <id>                 # Revoke a TokenHub API key
+atel key use                         # Print OpenAI-compatible env exports
+```
+
+### TokenHub & Account
+```bash
+atel balance                                # Show platform account balance
+atel deposit <amount> [channel]             # Add funds to the platform account
+atel withdraw <amount> [channel] [address]  # Withdraw funds
+atel transactions                           # List platform payment history
+
+atel hub balance                            # Show USDC and ATELToken balances
+atel hub dashboard                          # Show a compact TokenHub account summary
+atel hub usage [--model <id>] [--days 7]    # Show model usage history
+atel hub ledger [--page 1] [--limit 20]     # Show account transaction records
+atel hub swap-history [--page 1] [--limit 20] # Show swap records
+atel hub stats                              # Show public TokenHub stats
+atel hub models [--search gpt]              # List available models
+atel hub chat <model> "<prompt>" [--stream] # Send a quick chat request
+
+atel swap usdc <amount> [--chain bsc|base]  # Swap USDC to ATELToken
+atel swap token <amount> [--chain bsc|base] # Swap ATELToken to USDC
+atel transfer <to_did> <amount> [--memo "settlement"] # Transfer ATELToken
+```
+
+The grouped `atel hub key <...>` path remains available, but `atel key <...>` is the preferred entry point for new setups.
+
 ### Friend System
 ```bash
 # Friend Management
@@ -345,12 +396,15 @@ Friend system data is stored in `.atel/`:
 
 ## Documentation
 
-- [docs/START-HERE.md](docs/START-HERE.md) — One-page onboarding
-- [docs/QUICKSTART-5MIN.md](docs/QUICKSTART-5MIN.md) — 5-minute quickstart
-- [docs/API.md](docs/API.md) — Detailed API guide
-- [docs/AUDIT_SERVICE.md](docs/AUDIT_SERVICE.md) — Audit system guide
-- [docs/builtin-executor-guide.md](docs/builtin-executor-guide.md) — Built-in executor guide
-- [docs/protocol-specification.md](docs/protocol-specification.md) — Protocol specification
+- [START-HERE.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/START-HERE.md) — One-page onboarding
+- [QUICKSTART-5MIN.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/QUICKSTART-5MIN.md) — 5-minute quickstart
+- [quick-start.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/quick-start.md) — TokenHub quick-start flow
+- [API.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/API.md) — Detailed API guide
+- [AUDIT_SERVICE.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/AUDIT_SERVICE.md) — Audit system guide
+- [builtin-executor-guide.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/builtin-executor-guide.md) — Built-in executor guide
+- [protocol-specification.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/docs/protocol-specification.md) — Protocol specification
+- [skill/SKILL.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/skill/SKILL.md) — OpenClaw runtime and setup conventions
+- [CHANGELOG.md](https://github.com/LawrenceLiang-BTC/atel-sdk/blob/main/CHANGELOG.md) — Release notes
 
 ## Environment Variables
 
@@ -365,10 +419,10 @@ Friend system data is stored in `.atel/`:
 ## Current Status
 
 - [x] **Phase 0 MVP complete** — 13 modules implemented, core trust workflow end-to-end
-- [x] **241 tests in suite** — Unit/integration coverage across modules
+- [x] **Release verification** — `npm run build` and `npm test` are part of the publish flow
 - [x] **P2P friend system** — Relationship-based access control with temporary sessions
 - [x] **Audit system** — CoT reasoning verification with local LLM
-- [x] **Production deployment** — Platform + SDK deployed and tested
+- [x] **Production deployment** — Platform + SDK deployed and smoke-tested
 
 ## Roadmap
 

package/bin/atel.mjs

@@ -342,10 +342,14 @@ async function pushTradeNotification(eventType, payload, body) {
     try {
       if (target.channel === 'telegram' && target.botToken) {
         // Direct TG Bot API — no gateway needed
+        // Note: parse_mode is intentionally omitted. Templates render plain
+        // text (no HTML markup), and milestone payloads frequently contain
+        // raw `<` characters (e.g. "<5秒", "<30秒") that would otherwise
+        // trip Telegram's HTML parser and cause silent 400 drops.
         await fetch(`https://api.telegram.org/bot${target.botToken}/sendMessage`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ chat_id: target.target, text: message, parse_mode: 'HTML' }),
+          body: JSON.stringify({ chat_id: target.target, text: message }),
           signal: AbortSignal.timeout(5000),
         }).catch(() => {});
       } else if (target.channel === 'gateway') {
@@ -396,10 +400,11 @@ async function pushP2PNotification(eventType, payload = {}) {
   for (const target of enabled) {
     try {
       if (target.channel === 'telegram' && target.botToken) {
+        // parse_mode intentionally omitted — see pushTradeNotification for rationale
         await fetch(`https://api.telegram.org/bot${target.botToken}/sendMessage`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ chat_id: target.target, text: message, parse_mode: 'HTML' }),
+          body: JSON.stringify({ chat_id: target.target, text: message }),
           signal: AbortSignal.timeout(5000),
         }).catch(() => {});
       } else if (target.channel === 'gateway') {
@@ -3433,7 +3438,20 @@ Format:
           const orderId = order?.orderId;
           if (!orderId) continue;
           seenOrderIds.add(orderId);
-          await reconcileSingleTradeOrder(order);
+          // The list endpoint returns a slim projection that omits
+          // `description` / `taskRequest`. Re-fetch the full order so
+          // reconcileSingleTradeOrder has the authoritative order
+          // description — without it ORDER_CONTEXT.md / agent prompts
+          // would be missing the original task and the LLM would
+          // hallucinate a topic from the milestone title alone.
+          let fullOrder = order;
+          try {
+            const fetched = await fetchOrderState(orderId);
+            if (fetched) fullOrder = fetched;
+          } catch (e) {
+            log({ event: 'trade_reconcile_order_fetch_error', orderId, error: e.message });
+          }
+          await reconcileSingleTradeOrder(fullOrder);
         } catch (e) {
           log({ event: 'trade_reconcile_order_error', orderId: order?.orderId, status, error: e.message });
         }
@@ -3462,7 +3480,7 @@ Format:
     const event = body.eventType || body.event;
     const payload = body.payload || {};
     const eventId = body.eventId;
-    const prompt = body.prompt || payload.prompt;
+    let prompt = body.prompt || payload.prompt;
     const recommendedActions = body.recommendedActions || payload.recommendedActions;
 
     if (!event) {
@@ -3515,7 +3533,7 @@ Format:
 
     const dedupeKey = body.dedupeKey || `${event}:${body.orderId || payload.orderId || ''}`;
     const orderIdForCwd = body.orderId || payload.orderId || '';
-    const workspace = getOrderWorkspace(orderIdForCwd, {
+    let workspace = getOrderWorkspace(orderIdForCwd, {
       chain: payload.chain || body.chain || '',
       role: payload.executorDid === id.did ? 'executor' : (payload.requesterDid === id.did ? 'requester' : ''),
       status: payload.orderStatus || body.orderStatus || '',
@@ -3529,6 +3547,55 @@ Format:
     const hookCwd = workspace.dir;
     const atelCwd = getAtelWorkspaceRoot();
 
+    // ── Verifier context enrichment for milestone_submitted ──
+    // Platform-side prompt for milestone_submitted historically did not
+    // include the original order description, so the verifier LLM had no
+    // ground truth to compare against. We re-fetch the full order here so
+    // ORDER_CONTEXT.md (the LLM's authoritative source file) and the
+    // prompt both contain the original task. We do NOT impose rule
+    // checklists — judgment belongs to the agent.
+    if (event === 'milestone_submitted' && orderIdForCwd) {
+      try {
+        const fullOrder = await fetchOrderState(orderIdForCwd);
+        const fullDesc = (fullOrder?.description
+          || fullOrder?.Description
+          || fullOrder?.taskRequest?.description
+          || fullOrder?.TaskRequest?.description
+          || '');
+        if (fullDesc) {
+          workspace = getOrderWorkspace(orderIdForCwd, {
+            chain: fullOrder?.chain || fullOrder?.Chain || payload.chain || body.chain || '',
+            role: 'requester',
+            status: fullOrder?.status || fullOrder?.Status || 'executing',
+            phase: 'waiting_requester_verification',
+            currentMilestone: payload.milestoneIndex ?? '',
+            milestoneTitle: payload.milestoneDescription || '',
+            orderDescription: fullDesc,
+            milestoneObjective: payload.milestoneDescription || '',
+            resultSummary: payload.resultSummary || '',
+          });
+          // Only override the prompt if the platform-supplied one is missing
+          // the original task — newer platform builds embed it directly.
+          if (typeof prompt === 'string' && !prompt.includes(fullDesc)) {
+            const mIdx = payload.milestoneIndex ?? 0;
+            const mDesc = payload.milestoneDescription || '';
+            const subSummary = payload.resultSummary || '';
+            const submitCount = payload.submitCount || 1;
+            prompt = `你是 ATEL 发单方 Agent，正在评审执行方对里程碑 M${mIdx} 的提交。\n\n`
+              + `## 原任务\n${fullDesc}\n\n`
+              + `## 当前里程碑\nM${mIdx}: ${mDesc}\n\n`
+              + `## 执行方提交（第 ${submitCount}/3 次）\n${subSummary}\n\n`
+              + `请基于你自己的判断，评估这次提交是否真实地完成了原任务在当前里程碑应有的部分。如果符合原任务的要求和意图，PASS；如果偏离原任务、违反原任务的约束、或没有真正交付要求的内容，REJECT。\n\n`
+              + `通过：\ncd ~/atel-workspace && atel milestone-verify ${orderIdForCwd} ${mIdx} --pass\n\n`
+              + `不通过（必须给出具体理由）：\ncd ~/atel-workspace && atel milestone-verify ${orderIdForCwd} ${mIdx} --reject '具体原因'\n`;
+            log({ event: 'verifier_prompt_overridden', orderId: orderIdForCwd, milestoneIndex: mIdx });
+          }
+        }
+      } catch (e) {
+        log({ event: 'verifier_prompt_override_error', orderId: orderIdForCwd, error: e.message });
+      }
+    }
+
     // 3. Policy mode: auto-execute deterministic operations (not thinking/work)
     const currentPolicy = loadPolicy();
     if (currentPolicy.agentMode === 'policy') {
@@ -5896,6 +5963,7 @@ async function cmdOrder(executorDid, capType, price) {
     try { executorDid = resolveDID(executorDid); } catch (e) { console.error(e.message); process.exit(1); }
   }
   const description = rawArgs.find((a, i) => rawArgs[i-1] === '--desc') || '';
+  const chainArg = rawArgs.find((a, i) => rawArgs[i-1] === '--chain') || '';
   const id = requireIdentity();
   
   try {
@@ -5955,7 +6023,7 @@ async function cmdOrder(executorDid, capType, price) {
     };
 
     // Send to Platform
-    const data = await signedFetch('POST', '/trade/v1/order', {
+    const orderBody = {
       executorDid,
       capabilityType: capType,
       priceAmount: parseFloat(price),
@@ -5966,7 +6034,9 @@ async function cmdOrder(executorDid, capType, price) {
       taskRequest: taskRequest,
       taskSignature: taskSignature,
       intent: intentData,  // AVIP intent
-    });
+    };
+    if (chainArg) { orderBody.chain = chainArg; }
+    const data = await signedFetch('POST', '/trade/v1/order', orderBody);
     
     // For paid orders: show escrow info (chain escrow creation handled by Platform backend)
     if (data.orderId && parseFloat(price) > 0 && data.escrow?.escrowContract) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawrenceliang-btc/atel-sdk",
-  "version": "1.1.29",
+  "version": "1.1.31",
   "description": "ATEL Protocol SDK - Agent Trust & Exchange Layer",
   "repository": {
     "type": "git",
@@ -71,5 +71,5 @@
     "typescript": "^5.7.0",
     "vitest": "^3.2.4"
   },
-  "license": "UNLICENSED"
+  "license": "MIT"
 }