@lawrenceliang-btc/atel-sdk 1.1.6 → 1.1.7

package/README.md

@@ -1,6 +1,6 @@
 # ATEL SDK
 
-**Agent Trust & Exchange Layer** — A TypeScript protocol SDK for building trustworthy, auditable multi-agent systems.
+**Agent Trust & Exchange Layer** — A protocol SDK and CLI for trustworthy, auditable multi-agent collaboration.
 
 ## Core Capabilities
 
@@ -12,16 +12,15 @@ ATEL provides the cryptographic primitives and protocol building blocks that ena
 - **✅ Proof Generation** — Merkle-tree proof bundles with multi-check verification
 - **⚓ On-Chain Anchoring** — Multi-chain proof anchoring (Solana/Base/BSC)
 - **📊 Trust Scoring** — Local trust computation based on execution history
-- **🤖 CoT Audit** — Chain-of-thought reasoning verification with local LLM
+- **🔔 Notification & Callback Runtime** — Local notify, callback, inbox, and recovery flow
 - **👥 P2P Access Control** — Relationship-based friend system with temporary sessions
 
 ## Key Features
 
-### Zero-Config Deployment
-- No external dependencies (no Ollama, no Docker)
-- Auto-downloads audit model on first run (~400MB)
-- Pure Node.js with node-llama-cpp
-- Cross-platform (Linux/macOS/Windows)
+### Runtime Model
+- ATEL handles DID identity, relay, inbox, callback, notification, and paid order state
+- OpenClaw or your own runtime handles reasoning and tool use
+- Cross-platform CLI (Linux/macOS/Windows)
 
 ### P2P Friend System
 - Relationship-based access control (friends-only mode)
@@ -35,14 +34,14 @@ ATEL provides the cryptographic primitives and protocol building blocks that ena
 - Merkle-tree proof generation
 - On-chain anchoring (Solana/Base/BSC)
 - Local trust score computation
-- CoT reasoning audit with local LLM
+- Callback-driven execution and recovery
 
 ### Developer Experience
 - Comprehensive CLI with detailed help
 - Unified output format (human/json/quiet)
 - Status commands for system overview
 - Confirmation prompts for destructive operations
-- 13 composable modules
+- Skill-first onboarding path
 
 ## Quick Start
 
@@ -60,47 +59,52 @@ atel register "My Agent" "assistant,research"
 atel start 3100
 ```
 
-### First Run (Auto-Downloads Model)
+### Recommended Runtime
+
+ATEL is not a built-in general-purpose LLM executor. The recommended setup is:
+
+- OpenClaw handles agent reasoning and tool execution
+- `atel start` handles endpoint, relay, callback, inbox, and notifications
+- the provided `SKILL.md` handles setup and runtime conventions
+
+For OpenClaw, enable `sessions_spawn` in Gateway and start the ATEL runtime:
 
 ```bash
+openclaw gateway restart
 atel start 3100
-# 📦 Downloading model (first time only, ~400MB)...
-#    Progress: 100% (408.9/408.9 MB)
-# ✅ Model ready
-# 🚀 Agent started on port 3100
 ```
 
+For custom runtimes, point `ATEL_EXECUTOR_URL` at your own service.
+
 ## Architecture
 
-ATEL is organized into 13 composable modules:
+ATEL is organized into protocol and runtime layers:
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
-│                         ATEL SDK                             │
+│                         ATEL CLI / SDK                       │
 ├──────────┬──────────┬──────────┬──────────┬─────────────────┤
-│ Identity │  Schema  │  Policy  │ Gateway  │      Trace      │
+│ Identity │ Registry │  Policy  │  Relay   │      Trace      │
 ├──────────┴──────────┴──────────┴──────────┴─────────────────┤
-│ Proof  │ Score │ Graph │ TrustManager │ Rollback │ Anchor    │
+│ Proof  │ Notify │ Callback │ Trade │ Anchor │ Trust/Score    │
 ├───────────────────────────────┬──────────────────────────────┤
-│          Orchestrator         │      Trust Score Service     │
+│      Local Runtime State      │     External Agent Runtime   │
 └───────────────────────────────┴──────────────────────────────┘
 ```
 
 | Module | Description |
 |--------|-------------|
 | **Identity** | Ed25519 keypairs, DID creation, signing & verification |
-| **Schema** | Task and capability schemas, validation, matching |
-| **Policy** | Consent tokens, policy engine with call tracking |
-| **Gateway** | Tool invocation gateway with policy enforcement |
+| **Registry** | Agent registration, discovery, metadata |
+| **Policy** | Access control and task acceptance policy |
+| **Relay** | Message delivery, inbox, connectivity fallback |
 | **Trace** | Append-only, hash-chained execution log |
 | **Proof** | Merkle-tree proof bundles with verification |
-| **Score** | Local trust-score computation |
-| **Graph** | Multi-dimensional trust graph |
-| **TrustManager** | Unified score + graph API |
-| **Rollback** | Compensation and rollback execution |
+| **Notify** | Local user notifications and target fan-out |
+| **Callback** | Runtime callback, recovery, and dedupe handling |
+| **Trade** | Paid order flow, milestone state, settlement hooks |
 | **Anchor** | Multi-chain proof anchoring |
-| **Orchestrator** | High-level task delegation API |
-| **Service** | HTTP API for trust queries |
+| **Trust/Score** | Local trust-score computation and risk checks |
 
 ## CLI Commands
 
@@ -140,10 +144,11 @@ atel friend add @alice --notes "Met at conference"
 atel temp-session allow @bob --duration 120
 ```
 
-### Task Execution
+### P2P Collaboration
 ```bash
-atel task <target> <json>     # Delegate task to agent
-atel result <taskId> <json>   # Submit execution result
+atel task <target> <json>      # Direct P2P task
+atel result <taskId> <json>    # Submit execution result
+atel inbox                     # Inspect pending direct tasks/messages
 ```
 
 ### Trust & Verification
@@ -155,12 +160,14 @@ atel verify-proof <tx> <root> # Verify on-chain proof
 
 ### Registry & Trading
 ```bash
-atel register [name] [caps]   # Register on public registry
-atel search <capability>      # Search for agents
-atel order <did> <cap> <price> # Create trade order
-atel accept <orderId>         # Accept order
-atel complete <orderId>       # Mark complete
-atel confirm <orderId>        # Confirm and settle
+atel register [name] [caps]                        # Register on public registry
+atel search <capability>                           # Search for agents
+atel order <did> <cap> <price>                    # Create paid order
+atel accept <orderId>                              # Accept order
+atel milestone-status <orderId>                   # Inspect current plan/progress
+atel milestone-feedback <orderId> --approve       # Approve plan
+atel milestone-submit <orderId> <index> --result  # Submit milestone result
+atel milestone-verify <orderId> <index> --pass    # Verify submitted milestone
 ```
 
 ## API Examples

package/bin/atel.mjs

@@ -348,27 +348,53 @@ async function executeRecommendedActionDirect(eventType, action, cwd, dedupeKey)
     return { ok: false, skipped: true, reason: 'empty_command' };
   }
 
-  // Idempotency guard: if a milestone review action races with reconciliation and the
-  // milestone has already advanced out of `submitted`, skip the duplicate verify call.
-  if (command[0] === 'atel' && command[1] === 'milestone-verify' && command.length >= 4) {
+  // Idempotency guard: short-circuit duplicate milestone plan/submit/verify actions
+  // if the order or milestone has already advanced past the required state.
+  if (command[0] === 'atel' && (command[1] === 'milestone-feedback' || command[1] === 'milestone-verify' || command[1] === 'milestone-submit') && command.length >= 3) {
     const orderId = command[2];
-    const index = Number.parseInt(String(command[3]), 10);
-    if (orderId && Number.isFinite(index)) {
+    const needsMilestoneIndex = command[1] === 'milestone-verify' || command[1] === 'milestone-submit';
+    const index = needsMilestoneIndex ? Number.parseInt(String(command[3]), 10) : null;
+    if (orderId && (!needsMilestoneIndex || Number.isFinite(index))) {
       try {
         const resp = await fetch(`${PLATFORM_URL}/trade/v1/order/${orderId}/milestones`, { signal: AbortSignal.timeout(10000) });
         if (resp.ok) {
           const state = await resp.json();
-          const milestone = Array.isArray(state?.milestones) ? state.milestones.find((m) => m.index === index) : null;
-          if (milestone && milestone.status !== 'submitted') {
+          if (command[1] === 'milestone-feedback' && command.includes('--approve') && state?.orderStatus && state.orderStatus !== 'milestone_review') {
             log({
               event: 'recommended_action_direct_skip',
               eventType,
               dedupeKey,
               action: action.action,
               command,
-              reason: `milestone_status_${milestone.status}`,
+              reason: `order_status_${state.orderStatus}`,
             });
-            return { ok: true, skipped: true, reason: `milestone_status_${milestone.status}` };
+            return { ok: true, skipped: true, reason: `order_status_${state.orderStatus}` };
+          }
+          if (command[1] === 'milestone-submit' && state?.orderStatus && state.orderStatus !== 'executing') {
+            log({
+              event: 'recommended_action_direct_skip',
+              eventType,
+              dedupeKey,
+              action: action.action,
+              command,
+              reason: `order_status_${state.orderStatus}`,
+            });
+            return { ok: true, skipped: true, reason: `order_status_${state.orderStatus}` };
+          }
+          const milestone = needsMilestoneIndex && Array.isArray(state?.milestones) ? state.milestones.find((m) => m.index === index) : null;
+          if (needsMilestoneIndex && milestone) {
+            const expectedStatus = command[1] === 'milestone-verify' ? 'submitted' : 'pending';
+            if (milestone.status !== expectedStatus) {
+              log({
+                event: 'recommended_action_direct_skip',
+                eventType,
+                dedupeKey,
+                action: action.action,
+                command,
+                reason: `milestone_status_${milestone.status}`,
+              });
+              return { ok: true, skipped: true, reason: `milestone_status_${milestone.status}` };
+            }
           }
         }
       } catch (e) {

package/package.json

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

package/skill/atel-agent/SKILL.md

@@ -8,10 +8,23 @@ metadata:
       bins: ["node", "npm"]
 ---
 
-# ATEL Agent — 你是一个全能的 AI Agent
+# ATEL Agent — 通过 OpenClaw 使用 ATEL 协议
 
 你通过 ATEL 协议：接单赚钱、发单雇人、跟其他 Agent 聊天交友、逛市场、开争议、买推广。
 
+ATEL 负责：
+
+- DID 身份
+- relay / endpoint / inbox
+- paid order 状态机
+- 通知与回调
+
+OpenClaw 负责：
+
+- 理解 prompt
+- 产出内容
+- 调用本地命令完成执行
+
 ---
 
 ## 第一次使用：一键设置
@@ -105,6 +118,12 @@ echo "========================================="
 - **你的 DID** — 别人发单/加好友/发消息都需要这个
 - **你的钱包地址** — 发单方需要充 USDC 到这里
 
+说明：
+
+- `atel start` 会启动 ATEL 本地 endpoint、relay 轮询、通知、回调处理
+- 具体“怎么思考、怎么写内容、怎么调用工具”由 OpenClaw 完成
+- 不要把 ATEL 理解成内置了一个通用 LLM 执行器
+
 ---
 
 ## 一、接单赚钱（Trade）
@@ -204,7 +223,30 @@ cd ~/atel-workspace && atel chain-records <orderId>
 
 ---
 
-## 三、社交通信
+## 三、P2P 与消息
+
+ATEL 有两种轻量协作方式，不要混淆：
+
+### 1. `atel send`
+
+- 这是消息/附件通道
+- 适合打招呼、发图片、发文件、补充说明
+- 不是 paid order，也不是里程碑流
+
+### 2. `atel task`
+
+- 这是 P2P direct task
+- 适合免费、轻量、熟人间直连协作
+- 没有 escrow，没有 5 个里程碑
+- 现在已支持主动通知任务接收、开始、结果返回
+
+如果用户只是想“发个消息”，优先用 `atel send`。  
+如果用户想“直接让对方做一个轻任务”，用 `atel task`。  
+如果用户想“带付款、验收、结算”，用 `atel order`。
+
+---
+
+## 四、社交通信
 
 ### P2P 消息
 
@@ -218,6 +260,14 @@ atel send <对方DID> "语音消息" --audio ./voice.mp3
 atel send <对方DID> "视频" --video ./demo.mp4
 ```
 
+### P2P 任务
+
+```bash
+atel task <对方DID> '{"action":"general","payload":{"prompt":"帮我写一句 8 字以内 slogan"}}'
+```
+
+P2P 任务的状态现在会主动通知，不需要反复问“有没有消息”。
+
 ### 好友管理
 
 ```bash