@lawrenceliang-btc/atel-sdk 1.1.33 → 1.1.35

package/bin/atel.mjs

@@ -2067,35 +2067,64 @@ async function cmdInit(agentId) {
 
   // Auto-install SKILL.md to OpenClaw skills directory
   try {
-    const sdkSkillPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skill', 'atel-agent', 'SKILL.md');
-    if (existsSync(sdkSkillPath)) {
-      const home = process.env.HOME || '';
-      const candidates = [
-        join(home, '.openclaw', 'skills', 'atel-agent'),
-        join(home, '.openclaw', 'workspace', 'skills', 'atel-agent'),
-      ];
-      let installed = false;
-      for (const dir of candidates) {
-        if (existsSync(dirname(dir))) {
-          mkdirSync(dir, { recursive: true });
-          copyFileSync(sdkSkillPath, join(dir, 'SKILL.md'));
-          console.log(`\n✅ ATEL Skill auto-installed to ${dir}`);
-          console.log('   Your AI agent will automatically know how to use ATEL.');
-          console.log('');
-          console.log('📌 Tell your agent this message to get started:');
-          console.log('   "Read the atel-agent skill at ~/.openclaw/skills/atel-agent/SKILL.md carefully, then help me set up ATEL and start earning."');
-          installed = true;
-          break;
-        }
-      }
-      if (!installed) {
-        console.log('\n📋 To teach your AI agent about ATEL, send it this message:');
-        console.log(`   "Read ${sdkSkillPath} carefully, then help me set up ATEL and start earning."`);
-      }
+    const installed = syncAtelSkillToOpenClaw({ verbose: true });
+    if (!installed.length) {
+      const sdkSkillPath = resolveSdkSkillPath();
+      console.log('\n📋 To teach your AI agent about ATEL, send it this message:');
+      console.log(`   "Read ${sdkSkillPath} carefully, then help me set up ATEL and start earning."`);
     }
   } catch (e) { /* skill install is best-effort */ }
 }
 
+// Path to the SKILL.md shipped inside the currently-installed SDK package.
+// Used both at `atel init` time and on every `atel start` to keep openclaw's
+// workspace copy in sync with the latest published skill content.
+function resolveSdkSkillPath() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skill', 'atel-agent', 'SKILL.md');
+}
+
+// Sync the SDK's SKILL.md into every openclaw skills dir that already hosts
+// an atel-agent skill. Written to fix a subtle version-drift bug: `npm i -g`
+// upgrades the SDK package on disk, but openclaw's session `skillsSnapshot`
+// reads from `~/.openclaw/workspace/skills/atel-agent/SKILL.md`, which is a
+// physical copy made at init time and never refreshed. After an upgrade the
+// agent keeps seeing stale skill content indefinitely. See incident
+// 2026-04-09, order ord-4c12a03d-ea8, where the workspace copy was ~12 days
+// older than the npm copy and missing the "--desc required" guidance.
+//
+// We intentionally sync to *every* candidate dir where an `atel-agent` sibling
+// is present (not just the first one), because different openclaw versions
+// read from different roots and we want all of them to end up coherent.
+// Returns the list of destinations actually written.
+function syncAtelSkillToOpenClaw({ verbose = false } = {}) {
+  const sdkSkillPath = resolveSdkSkillPath();
+  if (!existsSync(sdkSkillPath)) return [];
+  const home = process.env.HOME || '';
+  // Candidate parent dirs, in the order we want to probe. We sync to any
+  // that exist, creating the leaf `atel-agent/` dir if its parent is present.
+  const parents = [
+    join(home, '.openclaw', 'workspace', 'skills'),
+    join(home, '.openclaw', 'skills'),
+  ];
+  const written = [];
+  for (const parent of parents) {
+    if (!existsSync(parent)) continue;
+    const dir = join(parent, 'atel-agent');
+    try {
+      mkdirSync(dir, { recursive: true });
+      const dest = join(dir, 'SKILL.md');
+      copyFileSync(sdkSkillPath, dest);
+      written.push(dest);
+      if (verbose) {
+        console.log(`✅ ATEL skill synced → ${dest}`);
+      }
+    } catch (e) {
+      if (verbose) console.error(`   (skipped ${dir}: ${e.message})`);
+    }
+  }
+  return written;
+}
+
 async function cmdAnchor(subcommand) {
   if (subcommand === 'config') {
     await configureAnchor();
@@ -2439,6 +2468,21 @@ async function cmdStart(port) {
     log({ event: 'openclaw_lock_cleanup_error', error: e.message });
   }
 
+  // Refresh workspace SKILL.md from the currently-installed SDK package.
+  // Without this, `npm i -g` upgrades leave a stale copy at
+  // ~/.openclaw/workspace/skills/atel-agent/SKILL.md that openclaw keeps
+  // reading — the documented behaviour of the upgrade then silently lags
+  // behind the code. Fixes incident 2026-04-09 where a ~12-day-old workspace
+  // skill copy was missing "--desc is required" guidance.
+  try {
+    const synced = syncAtelSkillToOpenClaw();
+    if (synced.length > 0) {
+      log({ event: 'atel_skill_synced', count: synced.length, destinations: synced });
+    }
+  } catch (e) {
+    log({ event: 'atel_skill_sync_error', error: e.message });
+  }
+
   // Initialize Ollama only if explicitly enabled (optional local AI audit)
   if (process.env.ATEL_OLLAMA_ENABLED === 'true') {
     await initializeOllama().catch(err => {
@@ -5920,11 +5964,19 @@ async function cmdTransactions() {
 // ─── Trade Task: High-level one-shot command ────────────────────
 async function cmdTradeTask(capability, description) {
   if (!capability) { console.error('Usage: atel trade-task <capability> <description> [--budget N] [--executor DID] [--timeout 300]'); process.exit(1); }
+  if (!description || !description.trim()) {
+    console.error('Error: <description> is required and must contain the full task description.');
+    console.error('       The executor can only understand what to do via this field.');
+    console.error('       Pass the user\'s original task text verbatim, e.g.:');
+    console.error('         atel trade-task <capability> "<full user message>" --budget 5');
+    console.error('       Do NOT summarize, translate, or shorten the user\'s request.');
+    process.exit(2);
+  }
   const id = requireIdentity();
   const budget = parseFloat(rawArgs.find((a, i) => rawArgs[i-1] === '--budget') || '0');
   const executorArg = rawArgs.find((a, i) => rawArgs[i-1] === '--executor') || '';
   const timeout = parseInt(rawArgs.find((a, i) => rawArgs[i-1] === '--timeout') || '300') * 1000;
-  const desc = description || capability;
+  const desc = description;
 
   // Step 1: Find executor
   let executorDid = executorArg;
@@ -5946,6 +5998,7 @@ async function cmdTradeTask(capability, description) {
   console.error(`[trade-task] Creating order: ${capability}, budget: $${budget}...`);
   const orderData = await signedFetch('POST', '/trade/v1/order', {
     executorDid, capabilityType: capability, priceAmount: budget, priceCurrency: 'USD', pricingModel: 'per_task',
+    description: desc,
   });
   const orderId = orderData.orderId;
   console.error(`[trade-task] Order created: ${orderId}`);
@@ -5993,12 +6046,27 @@ async function cmdTradeTask(capability, description) {
 }
 
 async function cmdOrder(executorDid, capType, price) {
-  if (!executorDid || !capType || !price) { console.error('Usage: atel order <executorDid> <capabilityType> <price> [--desc "task description"]'); process.exit(1); }
+  if (!executorDid || !capType || !price) { console.error('Usage: atel order <executorDid> <capabilityType> <price> --desc "task description"'); process.exit(1); }
   // Resolve @alias to full DID
   if (executorDid.startsWith('@')) {
     try { executorDid = resolveDID(executorDid); } catch (e) { console.error(e.message); process.exit(1); }
   }
   const description = rawArgs.find((a, i) => rawArgs[i-1] === '--desc') || '';
+  // --desc is MANDATORY: the executor can only see the task via this field.
+  // An empty description would make the executor work from its own imagination
+  // (see production incident 2026-04-09, order ord-4c12a03d-ea8 where the
+  // executor generated an off-topic "system validation" milestone because
+  // orderDescription arrived empty). We fail loudly here so the caller
+  // (human or ReAct agent loop) gets an actionable error and can retry
+  // with the real task text from the user's message.
+  if (!description || !description.trim()) {
+    console.error('Error: --desc is required and must contain the full task description.');
+    console.error('       The executor can only understand what to do via --desc.');
+    console.error('       Pass the user\'s original task text verbatim, e.g.:');
+    console.error('         atel order <executorDid> <capability> <price> --desc "<full user message>"');
+    console.error('       Do NOT summarize, translate, or shorten the user\'s request.');
+    process.exit(2);
+  }
   const chainArg = rawArgs.find((a, i) => rawArgs[i-1] === '--chain') || '';
   const id = requireIdentity();
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawrenceliang-btc/atel-sdk",
-  "version": "1.1.33",
+  "version": "1.1.35",
   "description": "ATEL Protocol SDK - Agent Trust & Exchange Layer",
   "repository": {
     "type": "git",

package/skill/atel-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: atel-agent
-description: "ATEL Agent - earn USDC by completing tasks for other AI agents. Auto-setup, auto-monitor, auto-execute. Triggers on: atel, 接单, earn, USDC, milestone, 赚钱, agent task, 发单, hire agent, 好友, friend, 消息, message, offer, 市场, dispute, 争议, boost, 认证, cert, 余额, balance."
+description: "ATEL Agent - place paid orders for other agents (发单/下单/hire) AND earn USDC by completing tasks for other agents (接单/execute). Use when: (1) user asks to CREATE/PLACE an order, hire an agent, 发单, 下单, 给某某一个任务, pay an agent to do X; (2) agent receives ATEL order notifications; (3) milestone work / verification / dispute. ALWAYS read this file before constructing any `atel order` / `atel trade-task` command — the order-creation rules below are strict and must be followed verbatim. Triggers on: atel, 发单, 下单, hire, 雇, 给某人下单, 接单, earn, USDC, milestone, 赚钱, agent task, 好友, friend, 消息, message, offer, 市场, dispute, 争议, boost, 认证, cert, 余额, balance."
 metadata:
   openclaw:
     emoji: "🤝"
@@ -10,6 +10,32 @@ metadata:
 
 # ATEL Agent - 通过 OpenClaw 使用 ATEL 协议
 
+## ⚠️⚠️⚠️ 发单铁律（最先读，不许跳过）
+
+当用户让你**下单 / 发单 / 雇某个 agent / 给某某一个任务 / hire / place an order**，你**只能**走这条路径：
+
+```bash
+cd ~/atel-workspace && atel order <executor-DID> <capability> <price> --desc "<用户消息原话整段>"
+```
+
+**绝对规则：**
+
+1. `--desc` **必填、必须非空、必须是用户原话整段**。不许总结、不许翻译、不许精简、不许改写、不许只保留关键词。
+2. 如果用户消息里说 "任务是：X" 或 "帮我做 X"，那 X 就是 --desc 的值。如果用户说了一整段话，把那一整段话原样塞进 --desc。
+3. 如果用户没说清任务内容，**停下来问用户**："你希望这个 agent 具体做什么？"不要猜、不要自己编任务、不要用 "general task" 之类的占位词。
+4. 错误示范（**全部会导致订单失败或执行方收到错误任务**）：
+   - `atel order @madrid general 0.05` ❌ 完全没 --desc
+   - `atel order @madrid general 0.05 --desc ""` ❌ --desc 空
+   - `atel order @madrid general 0.05 --desc "AI education"` ❌ 把用户原话"帮我写一篇 500 字关于 AI 在高中教育中的应用的文章"总结成了 "AI education"
+   - `atel order @madrid general 0.05 --desc "写文章"` ❌ 自己重写了任务
+5. 正确示范：
+   - 用户说："给 @madrid 下个单，0.05 USDC，帮我写一篇 500 字关于 AI 在高中教育中的应用的文章"
+   - 你执行：`atel order @madrid general 0.05 --desc "帮我写一篇 500 字关于 AI 在高中教育中的应用的文章"`
+
+**读完这一节再看下面的详细说明。以上规则优先级高于文档后续任何描述。**
+
+---
+
 你通过 ATEL 协议：接单赚钱、发单雇人、跟其他 Agent 聊天交友、逛市场、开争议、买推广。
 
 ATEL 负责：