@lawrenceliang-btc/atel-sdk 1.1.5 → 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

@@ -89,6 +89,8 @@ const PENDING_FILE = resolve(ATEL_DIR, 'pending-tasks.json');
 const RESULT_PUSH_QUEUE_FILE = resolve(ATEL_DIR, 'pending-result-pushes.json');
 const NOTIFY_TARGETS_FILE = resolve(ATEL_DIR, 'notify-targets.json');
 const TRADE_TRACK_FILE = resolve(ATEL_DIR, 'tracked-orders.json');
+const P2P_STATUS_FILE = resolve(ATEL_DIR, 'p2p-task-status.jsonl');
+const PENDING_AGENT_CALLBACKS_FILE = resolve(ATEL_DIR, 'pending-agent-callbacks.json');
 const KEYS_DIR = resolve(ATEL_DIR, 'keys');
 const ANCHOR_FILE = resolve(KEYS_DIR, 'anchor.json');
 
@@ -244,33 +246,155 @@ async function pushTradeNotification(eventType, payload, body) {
   try { saveNotifyTargets(targets); } catch {}
 }
 
+function appendP2PTaskStatus(entry) {
+  if (!entry?.taskId || !entry?.status) return;
+  ensureDir();
+  appendFileSync(P2P_STATUS_FILE, `${JSON.stringify({ updatedAt: new Date().toISOString(), ...entry })}\n`);
+}
+
+async function pushP2PNotification(eventType, payload = {}) {
+  const targets = loadNotifyTargets();
+  const enabled = (targets.targets || []).filter(t => t.enabled !== false);
+  if (enabled.length === 0) return;
+
+  const templates = {
+    'p2p_task_sent': (p) => `📤 P2P任务已发送\n任务: ${p.taskId || '?'}\n目标: ${p.peerDid || '?'}`,
+    'p2p_task_received': (p) => `📩 收到新的P2P任务\n任务: ${p.taskId || '?'}\n来自: ${p.peerDid || '?'}`,
+    'p2p_task_started': (p) => `▶️ P2P任务开始处理\n任务: ${p.taskId || '?'}\n来自: ${p.peerDid || '?'}`,
+    'p2p_result_submitted': (p) => `📨 P2P结果已发回对方\n任务: ${p.taskId || '?'}\n目标: ${p.peerDid || '?'}`,
+    'p2p_result_received': (p) => `✅ P2P任务已完成\n任务: ${p.taskId || '?'}\n结果: ${String(p.result || '').slice(0, 80) || '已返回'}`,
+    'p2p_task_failed': (p) => `❌ P2P任务失败\n任务: ${p.taskId || '?'}\n原因: ${p.reason || '未知错误'}`,
+  };
+  const tmpl = templates[eventType];
+  if (!tmpl) return;
+  const message = tmpl(payload);
+
+  for (const target of enabled) {
+    try {
+      if (target.channel === 'telegram' && target.botToken) {
+        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' }),
+          signal: AbortSignal.timeout(5000),
+        }).catch(() => {});
+      } else if (target.channel === 'gateway') {
+        const gw = discoverGateway();
+        if (gw?.url && gw?.token) {
+          await fetch(`${gw.url}/tools/invoke`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${gw.token}` },
+            body: JSON.stringify({ tool: 'message', args: { action: 'send', message, target: target.target } }),
+            signal: AbortSignal.timeout(5000),
+          }).catch(() => {});
+        }
+      }
+      target.lastUsedAt = new Date().toISOString();
+    } catch {}
+  }
+  try { saveNotifyTargets(targets); } catch {}
+}
+
+function loadPendingAgentCallbacksPersisted() {
+  if (!existsSync(PENDING_AGENT_CALLBACKS_FILE)) return {};
+  try {
+    const data = JSON.parse(readFileSync(PENDING_AGENT_CALLBACKS_FILE, 'utf-8'));
+    return data && typeof data === 'object' ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+function savePendingAgentCallbacksPersisted(data) {
+  ensureDir();
+  writeFileSync(PENDING_AGENT_CALLBACKS_FILE, JSON.stringify(data, null, 2));
+}
+
+function persistPendingAgentCallback(dedupeKey, data) {
+  if (!dedupeKey || !data) return;
+  const persisted = loadPendingAgentCallbacksPersisted();
+  persisted[dedupeKey] = {
+    ...data,
+    updatedAt: new Date().toISOString(),
+  };
+  savePendingAgentCallbacksPersisted(persisted);
+}
+
+function markPersistedPendingAgentCallbackCompleted(dedupeKey, meta = {}) {
+  if (!dedupeKey) return;
+  const persisted = loadPendingAgentCallbacksPersisted();
+  const existing = persisted[dedupeKey];
+  persisted[dedupeKey] = {
+    ...(existing || {}),
+    ...meta,
+    terminal: true,
+    completedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  savePendingAgentCallbacksPersisted(persisted);
+}
+
+function clearPersistedPendingAgentCallback(dedupeKey) {
+  if (!dedupeKey) return;
+  const persisted = loadPendingAgentCallbacksPersisted();
+  if (!persisted[dedupeKey]) return;
+  delete persisted[dedupeKey];
+  savePendingAgentCallbacksPersisted(persisted);
+}
+
 async function executeRecommendedActionDirect(eventType, action, cwd, dedupeKey) {
   const command = Array.isArray(action?.command) ? action.command.filter(Boolean) : [];
   if (command.length === 0) {
     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: `order_status_${state.orderStatus}`,
+            });
+            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: `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}` };
+          }
+          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) {
@@ -2392,6 +2516,63 @@ async function cmdStart(port) {
     const dedupeKey = body.dedupeKey;
     const pending = dedupeKey ? pendingAgentCallbacks.get(dedupeKey) : null;
     if (!pending) {
+      const persisted = dedupeKey ? loadPendingAgentCallbacksPersisted()[dedupeKey] : null;
+      if (persisted?.terminal) {
+        log({
+          event: 'callback_late_skip',
+          dedupeKey,
+          eventType: persisted.eventType || body?.eventType || 'unknown',
+          callback_source: persisted.source || 'unknown',
+        });
+        res.json({ status: 'ok', skipped: true, reason: 'late_callback_after_completion' });
+        return;
+      }
+      log({
+        event: 'callback_404',
+        callback_404_type: 'unknown_dedupeKey',
+        dedupeKey,
+        callback_404_recovered: !!persisted,
+        callback_source: persisted?.source || 'unknown',
+        eventType: persisted?.eventType || body?.eventType || 'unknown',
+      });
+      if (persisted) {
+        const callbackAction = buildAgentCallbackAction(persisted.eventType, persisted.payload || {}, body);
+        if (callbackAction.ok && callbackAction.action?.type === 'local_result') {
+          try {
+            const localResp = await fetch(`http://127.0.0.1:${p}/atel/v1/result`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                taskId: callbackAction.action.taskId,
+                result: callbackAction.action.result,
+                success: true,
+              }),
+              signal: AbortSignal.timeout(15000),
+            });
+            const localBody = await localResp.json().catch(() => ({}));
+            if (localResp.ok) {
+              clearPersistedPendingAgentCallback(dedupeKey);
+              res.json({ status: 'ok', recovered: true });
+              return;
+            }
+            res.status(500).json({ error: localBody.error || 'local_result_callback_failed', recovered: false });
+            return;
+          } catch (e) {
+            res.status(500).json({ error: e.message || 'local_result_callback_failed', recovered: false });
+            return;
+          }
+        }
+        if (callbackAction.ok) {
+          const execResult = await executeRecommendedActionDirect(persisted.eventType, callbackAction.action, persisted.cwd || process.cwd(), dedupeKey);
+          if (execResult.ok) {
+            clearPersistedPendingAgentCallback(dedupeKey);
+            res.json({ status: 'ok', recovered: true });
+            return;
+          }
+          res.status(500).json({ error: execResult.error || 'callback_action_failed', recovered: false });
+          return;
+        }
+      }
       res.status(404).json({ error: 'Unknown dedupeKey' });
       return;
     }
@@ -2407,6 +2588,7 @@ async function cmdStart(port) {
 
     if (body.status === 'failed') {
       pendingAgentCallbacks.delete(dedupeKey);
+      clearPersistedPendingAgentCallback(dedupeKey);
       pending.resolve({ ok: false, body, error: body.error || 'agent_reported_failed' });
       res.json({ status: 'ok' });
       return;
@@ -2415,12 +2597,14 @@ async function cmdStart(port) {
     const callbackAction = buildAgentCallbackAction(pending.eventType, pending.payload || {}, body);
     if (callbackAction.skipped) {
       pendingAgentCallbacks.delete(dedupeKey);
+      markPersistedPendingAgentCallbackCompleted(dedupeKey, { eventType: pending.eventType, payload: pending.payload, cwd: pending.cwd, source: dedupeKey?.startsWith('reconcile:') ? 'reconcile' : 'main', skipped: true, reason: callbackAction.reason });
       pending.resolve({ ok: true, skipped: true, body, reason: callbackAction.reason });
       res.json({ status: 'ok', skipped: true });
       return;
     }
     if (!callbackAction.ok) {
       pendingAgentCallbacks.delete(dedupeKey);
+      clearPersistedPendingAgentCallback(dedupeKey);
       pending.resolve({ ok: false, body, error: callbackAction.error || 'invalid_callback_payload' });
       res.status(400).json({ error: callbackAction.error || 'invalid_callback_payload' });
       return;
@@ -2440,6 +2624,11 @@ async function cmdStart(port) {
         });
         const localBody = await localResp.json().catch(() => ({}));
         pendingAgentCallbacks.delete(dedupeKey);
+        if (localResp.ok) {
+          markPersistedPendingAgentCallbackCompleted(dedupeKey, { eventType: pending.eventType, payload: pending.payload, cwd: pending.cwd, source: dedupeKey?.startsWith('reconcile:') ? 'reconcile' : 'main', action: callbackAction.action, localBody });
+        } else {
+          clearPersistedPendingAgentCallback(dedupeKey);
+        }
         pending.resolve({ ok: localResp.ok, body, action: callbackAction.action, localBody });
         if (!localResp.ok) {
           res.status(500).json({ error: localBody.error || 'local_result_callback_failed' });
@@ -2449,6 +2638,7 @@ async function cmdStart(port) {
         return;
       } catch (e) {
         pendingAgentCallbacks.delete(dedupeKey);
+        clearPersistedPendingAgentCallback(dedupeKey);
         pending.resolve({ ok: false, body, action: callbackAction.action, error: e.message });
         res.status(500).json({ error: e.message || 'local_result_callback_failed' });
         return;
@@ -2457,6 +2647,11 @@ async function cmdStart(port) {
 
     const execResult = await executeRecommendedActionDirect(pending.eventType, callbackAction.action, pending.cwd || process.cwd(), dedupeKey);
     pendingAgentCallbacks.delete(dedupeKey);
+    if (execResult.ok) {
+      markPersistedPendingAgentCallbackCompleted(dedupeKey, { eventType: pending.eventType, payload: pending.payload, cwd: pending.cwd, source: dedupeKey?.startsWith('reconcile:') ? 'reconcile' : 'main', action: callbackAction.action });
+    } else {
+      clearPersistedPendingAgentCallback(dedupeKey);
+    }
     pending.resolve({ ok: execResult.ok, body, action: callbackAction.action, execResult });
     if (!execResult.ok) {
       res.status(500).json({ error: execResult.error || 'callback_action_failed' });
@@ -2554,6 +2749,7 @@ ${callbackFailed}
     return await new Promise(async (resolve) => {
       const timer = setTimeout(() => {
         pendingAgentCallbacks.delete(dedupeKey);
+        persistPendingAgentCallback(dedupeKey, { eventType, payload, cwd, source: dedupeKey.startsWith('reconcile:') ? 'reconcile' : 'main', timeout: true });
         resolve({ ok: false, error: 'agent_callback_timeout' });
       }, timeoutMs);
 
@@ -2567,6 +2763,12 @@ ${callbackFailed}
           resolve(result);
         },
       });
+      persistPendingAgentCallback(dedupeKey, {
+        eventType,
+        payload,
+        cwd,
+        source: dedupeKey.startsWith('reconcile:') ? 'reconcile' : 'main',
+      });
 
       try {
         const resp = await fetch(`${gw.url}/tools/invoke`, {
@@ -2586,6 +2788,7 @@ ${callbackFailed}
         });
         if (!resp.ok) {
           pendingAgentCallbacks.delete(dedupeKey);
+          clearPersistedPendingAgentCallback(dedupeKey);
           clearTimeout(timer);
           resolve({ ok: false, error: `sessions_spawn_http_${resp.status}` });
           return;
@@ -2598,6 +2801,7 @@ ${callbackFailed}
         log({ event: 'agent_session_spawned', eventType, dedupeKey, childSessionKey });
       } catch (e) {
         pendingAgentCallbacks.delete(dedupeKey);
+        clearPersistedPendingAgentCallback(dedupeKey);
         clearTimeout(timer);
         resolve({ ok: false, error: e.message });
       }
@@ -2958,7 +3162,24 @@ ${callbackFailed}
   // Result callback: POST /atel/v1/result (executor calls this when done)
   endpoint.app?.post?.('/atel/v1/result', async (req, res) => {
     const { taskId, result, success, trace: executorTrace } = req.body || {};
-    if (!taskId || !pendingTasks[taskId]) { res.status(404).json({ error: 'Unknown taskId' }); return; }
+    if (!taskId || !pendingTasks[taskId]) {
+      try {
+        if (existsSync(P2P_STATUS_FILE)) {
+          const lines = readFileSync(P2P_STATUS_FILE, 'utf-8').split('\n').filter(Boolean);
+          for (let i = lines.length - 1; i >= 0; i--) {
+            const entry = JSON.parse(lines[i]);
+            if (entry?.taskId === taskId && entry?.status === 'result_received') {
+              log({ event: 'callback_late_skip', taskId, callback_source: 'result' });
+              res.json({ status: 'ok', skipped: true, reason: 'late_result_after_completion' });
+              return;
+            }
+          }
+        }
+      } catch {}
+      log({ event: 'callback_404', callback_404_type: 'unknown_taskId', taskId, callback_404_recovered: false, callback_source: 'result' });
+      res.status(404).json({ error: 'Unknown taskId' });
+      return;
+    }
 
     // Milestone auto-execution removed. Agent handles results via its own AI.
     const task = pendingTasks[taskId];
@@ -3242,6 +3463,8 @@ ${callbackFailed}
     }
 
     log({ event: 'result_push_starting', taskId, hasSenderEndpoint: !!task.senderEndpoint, hasSenderCandidates: !!(task.senderCandidates?.length) });
+    appendP2PTaskStatus({ taskId, role: 'executor', peerDid: task.from, status: 'result_submitted', result });
+    pushP2PNotification('p2p_result_submitted', { taskId, peerDid: task.from, result }).catch(() => {});
 
     // Push result back to sender
     // Re-lookup sender if we don't have their endpoint (e.g., lookup failed at accept time)
@@ -3302,6 +3525,13 @@ ${callbackFailed}
     }
     } catch (pushErr) { log({ event: 'result_push_outer_error', taskId, error: pushErr.message, stack: pushErr.stack?.split('\n')[1]?.trim() }); }
 
+    appendP2PTaskStatus({ taskId, role: 'requester', peerDid: task.from, status: 'result_received', result });
+    pushP2PNotification(success === false ? 'p2p_task_failed' : 'p2p_result_received', {
+      taskId,
+      peerDid: task.from,
+      result,
+      reason: success === false ? (result?.error || 'execution_failed') : null,
+    }).catch(() => {});
     delete pendingTasks[taskId]; saveTasks(pendingTasks);
     res.json({ status: 'ok', proof_id: proof.proof_id, anchor_tx: anchor?.txHash || null });
   });
@@ -3483,6 +3713,13 @@ ${callbackFailed}
     // Ignore task-result messages (these are responses, not new tasks)
     if (message.type === 'task-result' || payload.status === 'completed' || payload.status === 'failed') {
       log({ event: 'result_received', type: 'task-result', from: message.from, taskId: payload.taskId, status: payload.status, proof: payload.proof || null, anchor: payload.anchor || null, execution: payload.execution || null, result: payload.result || null, timestamp: new Date().toISOString() });
+      appendP2PTaskStatus({ taskId: payload.taskId, role: 'requester', peerDid: message.from, status: 'result_received', result: payload.result || null });
+      pushP2PNotification(payload.status === 'failed' ? 'p2p_task_failed' : 'p2p_result_received', {
+        taskId: payload.taskId,
+        peerDid: message.from,
+        result: payload.result || null,
+        reason: payload.error || payload.result?.error || null,
+      }).catch(() => {});
       return { status: 'ok', message: 'Result received' };
     }
 
@@ -3597,10 +3834,12 @@ ${callbackFailed}
           encrypted: !!session?.encrypted,
           reason: 'open_mode_requires_confirm'
         };
-        savePending(pending);
-        
-        log({ 
-          event: 'task_queued', 
+      savePending(pending);
+      appendP2PTaskStatus({ taskId, role: 'executor', peerDid: message.from, status: 'task_received' });
+      pushP2PNotification('p2p_task_received', { taskId, peerDid: message.from }).catch(() => {});
+      
+      log({ 
+        event: 'task_queued', 
           taskId, 
           from: message.from, 
           action, 
@@ -3659,6 +3898,8 @@ ${callbackFailed}
         encrypted: !!session?.encrypted,
       };
       savePending(pending);
+      appendP2PTaskStatus({ taskId, role: 'executor', peerDid: message.from, status: 'task_received' });
+      pushP2PNotification('p2p_task_received', { taskId, peerDid: message.from }).catch(() => {});
       log({ event: 'task_queued', taskId, from: message.from, action, reason: taskMode === 'confirm' ? 'task_mode_confirm' : 'autoAcceptP2P_off', timestamp: new Date().toISOString() });
       return { status: 'queued', taskId, message: 'Task queued for manual confirmation. Use: atel approve ' + taskId };
     }
@@ -3690,14 +3931,21 @@ ${callbackFailed}
       sessionId: accessCheck.sessionId
     };
     saveTasks(pendingTasks);
+    appendP2PTaskStatus({ taskId, role: 'executor', peerDid: message.from, status: 'task_received' });
     log({ event: 'task_accepted', taskId, from: message.from, action, encrypted: !!session?.encrypted, relationship: accessCheck.relationship, timestamp: new Date().toISOString() });
 
     // Forward to executor, gateway session, or echo fallback
     if (EXECUTOR_URL) {
+      appendP2PTaskStatus({ taskId, role: 'executor', peerDid: message.from, status: 'task_started' });
+      pushP2PNotification('p2p_task_received', { taskId, peerDid: message.from }).catch(() => {});
+      pushP2PNotification('p2p_task_started', { taskId, peerDid: message.from }).catch(() => {});
       fetch(EXECUTOR_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ taskId, from: message.from, action, payload, encrypted: !!session?.encrypted, toolProxy: `http://127.0.0.1:${toolProxyPort}` }) }).catch(e => log({ event: 'executor_forward_failed', taskId, error: e.message }));
       return { status: 'accepted', taskId, message: 'Task accepted. Result will be pushed when ready.' };
     } else {
       const p2pPrompt = `你是 ATEL 接单方 Agent，收到一个 P2P 任务。\n任务类型：${action}\n任务内容：${JSON.stringify(payload?.payload || payload || {}, null, 2)}\n请认真完成任务，并通过回调返回最终结果。`;
+      appendP2PTaskStatus({ taskId, role: 'executor', peerDid: message.from, status: 'task_started' });
+      pushP2PNotification('p2p_task_received', { taskId, peerDid: message.from }).catch(() => {});
+      pushP2PNotification('p2p_task_started', { taskId, peerDid: message.from }).catch(() => {});
       const queued = queueAgentHook('p2p_task', `p2p:${taskId}`, p2pPrompt, process.cwd(), { taskId });
       if (queued) {
         return { status: 'accepted', taskId, message: 'Task accepted. Result will be pushed when ready.' };
@@ -3715,6 +3963,8 @@ ${callbackFailed}
       const anchor = await anchorOnChain(proof.trace_root, { proof_id: proof.proof_id, executorDid: id.did, requesterDid: message.from, action, taskId });
       const echoAcceptedAt = pendingTasks[taskId]?.acceptedAt;
       delete pendingTasks[taskId]; saveTasks(pendingTasks);
+      appendP2PTaskStatus({ taskId, role: 'executor', peerDid: message.from, status: 'task_failed', reason: 'no_executor' });
+      pushP2PNotification('p2p_task_failed', { taskId, peerDid: message.from, reason: 'no_executor' }).catch(() => {});
 
       // ── Trust Score + Graph Update (echo mode) ──
       try {
@@ -4346,10 +4596,13 @@ async function cmdTask(target, taskJson) {
     const relayAck = await relaySend('/atel/v1/task', msg);
 
     console.log(JSON.stringify({ status: 'task_sent', remoteDid, via: 'relay', relay_ack: relayAck, note: 'Relay mode is async. Waiting for result (up to 120s)...' }));
+    const relayTaskId = relayAck?.result?.taskId || msg.id || msg.payload?.taskId;
+    appendP2PTaskStatus({ taskId: relayTaskId, role: 'requester', peerDid: remoteDid, status: 'task_sent' });
+    pushP2PNotification('p2p_task_sent', { taskId: relayTaskId, peerDid: remoteDid }).catch(() => {});
 
     // Wait for result to arrive in inbox (poll for task-result)
     // Extract taskId from relay ack (assigned by remote agent), fallback to msg fields
-    const taskId = relayAck?.result?.taskId || msg.id || msg.payload?.taskId;
+    const taskId = relayTaskId;
     let result = null;
     const waitStart = Date.now();
     const WAIT_TIMEOUT = 120000; // 2 minutes
@@ -4429,6 +4682,9 @@ async function cmdTask(target, taskJson) {
     const msg = createMessage({ type: 'task', from: id.did, to: remoteDid, payload: enhancedPayload, secretKey: id.secretKey });
     const result = await client.sendTask(remoteEndpoint, msg, hsManager);
     console.log(JSON.stringify({ status: 'task_sent', remoteDid, via: remoteEndpoint, result }, null, 2));
+    const directTaskId = result?.taskId || taskRequest.taskId || msg.id || msg.payload?.taskId;
+    appendP2PTaskStatus({ taskId: directTaskId, role: 'requester', peerDid: remoteDid, status: 'task_sent' });
+    pushP2PNotification('p2p_task_sent', { taskId: directTaskId, peerDid: remoteDid }).catch(() => {});
 
     // Update local trust history
     const success = result?.status !== 'rejected' && result?.status !== 'failed';

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@lawrenceliang-btc/atel-sdk",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "ATEL Protocol SDK - Agent Trust & Exchange Layer",
   "repository": {
     "type": "git",
-    "url": "https://github.com/LawrenceLiang-BTC/atel-sdk.git"
+    "url": "git+https://github.com/LawrenceLiang-BTC/atel-sdk.git"
   },
   "type": "module",
   "main": "./dist/index.js",
@@ -16,7 +16,7 @@
   },
   "types": "./dist/index.d.ts",
   "bin": {
-    "atel": "./bin/atel.mjs"
+    "atel": "bin/atel.mjs"
   },
   "files": [
     "dist",

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