@lawrenceliang-btc/atel-sdk 0.9.23 → 1.0.0

package/bin/atel.mjs

@@ -56,7 +56,7 @@ import { resolve, join } from 'node:path';
 import crypto from 'node:crypto';
 import {
   AgentIdentity, AgentEndpoint, AgentClient, HandshakeManager,
-  createMessage, RegistryClient, ExecutionTrace, ProofGenerator,
+  createMessage, verifyMessage, parseDID, RegistryClient, ExecutionTrace, ProofGenerator,
   SolanaAnchorProvider, BaseAnchorProvider, BSCAnchorProvider,
   autoNetworkSetup, collectCandidates, connectToAgent,
   discoverPublicIP, checkReachable, ContentAuditor, TrustScoreClient,
@@ -64,7 +64,9 @@ import {
   TrustGraph, calculateTaskWeight,
 } from '@lawrenceliang-btc/atel-sdk';
 import { TunnelManager, HeartbeatManager } from './tunnel-manager.mjs';
-import { initializeOllama, getOllamaStatus } from './ollama-manager.mjs';
+// ollama-manager removed — SDK does not run local models
+const initializeOllama = async () => {};
+const getOllamaStatus = async () => ({ running: false, models: [] });
 import { parseAttachmentFlags, processAttachments } from './atel-attachment-helpers.mjs';
 
 const ATEL_DIR = resolve(process.env.ATEL_DIR || '.atel');
@@ -258,6 +260,23 @@ Friend Management Commands:
     Examples:
       atel friend status
 
+── How Friend System Affects Communication ──────────────────────────
+
+  By default, agents operate in "friends_only" mode:
+    • P2P messages (atel send) and tasks will be REJECTED if you are not a friend
+    • You must send a friend request and have it accepted first
+
+  Typical flow to communicate with a new agent:
+    1. atel friend request <their-did> --message "Hi, lets connect!"
+    2. They run: atel friend pending         (to see your request)
+    3. They run: atel friend accept <req-id> (to accept)
+    4. Now you can: atel send <their-did> "Hello!"
+
+  To allow communication WITHOUT friend relationship (open mode):
+    Edit .atel/policy.json and set:
+    { "relationshipPolicy": { "defaultMode": "open" } }
+    Restart your agent. Both sides can configure this independently.
+
 For more information, visit: https://docs.atel.io/friend-system
   `);
 }
@@ -1927,25 +1946,13 @@ async function cmdStart(port) {
   const toolGatewayServer = await startToolGatewayProxy(toolProxyPort, id, policy);
   log({ event: 'tool_gateway_started', port: toolProxyPort });
 
-  // ── Built-in Executor (auto-start if no external ATEL_EXECUTOR_URL) ──
-  let builtinExecutor = null;
-  if (!EXECUTOR_URL) {
-    const executorPort = p + 2;
-    try {
-      const { BuiltinExecutor } = await import('../dist/executor/index.js');
-      builtinExecutor = new BuiltinExecutor({
-        port: executorPort,
-        callbackUrl: `http://127.0.0.1:${p}/atel/v1/result`,
-        gatewayUrl: getGatewayUrl(),
-        contextPath: join(ATEL_DIR, 'agent-context.md'),
-        log,
-      });
-      await builtinExecutor.start();
-      EXECUTOR_URL = `http://127.0.0.1:${executorPort}`;
-      log({ event: 'builtin_executor_started', port: executorPort, url: EXECUTOR_URL });
-    } catch (e) {
-      log({ event: 'builtin_executor_failed', error: e.message, note: 'Falling back to echo mode. Set ATEL_EXECUTOR_URL for external executor.' });
-    }
+  // ── Executor: Agent brings their own AI. SDK does not run a built-in executor. ──
+  // If ATEL_EXECUTOR_URL is set, P2P tasks are forwarded there.
+  // Milestone work is done by the Agent itself (not the SDK).
+  if (EXECUTOR_URL) {
+    log({ event: 'external_executor_configured', url: EXECUTOR_URL });
+  } else {
+    log({ event: 'no_executor', note: 'No ATEL_EXECUTOR_URL set. Agent handles tasks via notifications + CLI.' });
   }
 
   // ── Trust Score Client (persistent) ──
@@ -2067,17 +2074,74 @@ async function cmdStart(port) {
     }
   });
 
-  // Webhook notification: POST /atel/v1/notify (platform calls this for order events)
+  // ── Event dedup (processed eventIds) ──
+  const processedEvents = new Set();
+
+  // Webhook notification: POST /atel/v1/notify
+  // SDK only: logs, writes inbox, prints prompt. Does NOT execute any actions.
+  // Agent reads inbox or webhook to decide what to do.
   endpoint.app?.post?.('/atel/v1/notify', async (req, res) => {
-    const { event, payload } = req.body || {};
-    if (!event || !payload) {
-      res.status(400).json({ error: 'event and payload required' });
+    const body = req.body || {};
+    // Support both old format {event, payload} and new format {eventId, eventType, payload}
+    const event = body.eventType || body.event;
+    const payload = body.payload || {};
+    const eventId = body.eventId;
+    const prompt = body.prompt || payload.prompt;
+    const recommendedActions = body.recommendedActions || payload.recommendedActions;
+
+    if (!event) {
+      res.status(400).json({ error: 'event/eventType required' });
       return;
     }
 
-    log({ event: 'webhook_received', type: event, payload });
+    // Dedup: skip already processed events
+    if (eventId && processedEvents.has(eventId)) {
+      log({ event: 'event_dedup_skip', eventId, eventType: event });
+      res.json({ status: 'already_processed', eventId });
+      return;
+    }
+    if (eventId) {
+      processedEvents.add(eventId);
+      // Keep set bounded
+      if (processedEvents.size > 1000) {
+        const first = processedEvents.values().next().value;
+        processedEvents.delete(first);
+      }
+    }
+
+    // Log the full event
+    log({ event: 'notification_received', eventId, eventType: event, orderId: body.orderId || payload.orderId, prompt: prompt ? prompt.substring(0, 100) : undefined });
+
+    // ── Universal notification handler: print prompt + log + respond ──
+    // SDK does NOT execute any actions. Agent reads inbox/webhook and decides.
+    if (prompt) {
+      console.log(`\n📨 [${event}] ${prompt.split('\n')[0]}`);
+    }
+    if (recommendedActions && Array.isArray(recommendedActions)) {
+      for (const action of recommendedActions) {
+        if (action.command) console.log(`   → ${action.command.join(' ')}`);
+      }
+    }
+    console.log('');
+
+    // Write full event to inbox for Agent program to read
+    log({
+      event: 'notification',
+      eventId,
+      eventType: event,
+      orderId: body.orderId || payload.orderId,
+      payload,
+      prompt,
+      recommendedActions,
+      sequenceNo: body.sequenceNo,
+      dedupeKey: body.dedupeKey,
+    });
+
+    res.json({ status: 'received', eventId, eventType: event });
+    return;
 
-    if (event === 'order_created') {
+    // ── Legacy event handlers below (kept but unreachable for reference) ──
+    if (event === 'order_created_legacy') {
       // New order notification - decide whether to accept
       const { orderId, requesterDid, capabilityType, priceAmount, description } = payload;
       
@@ -2178,35 +2242,55 @@ async function cmdStart(port) {
         return;
       }
 
-      // Auto-accept (default)
+      // Auto-accept with retry (default)
       log({ event: 'order_auto_accept', orderId, requesterDid, capabilityType });
-      
-      // Call platform API to accept
-      try {
-        const timestamp = new Date().toISOString(); // RFC3339 format
-        const payload = {}; // Empty payload for accept
-        const signPayload = { did: id.did, timestamp, payload };
-        const signature = sign(signPayload, id.secretKey);
-        
-        const signedRequest = {
-          did: id.did,
-          timestamp,
-          signature,
-          payload
-        };
-        
-        log({ event: 'order_accept_calling_api', orderId, platform: ATEL_PLATFORM });
-        
-        const acceptResp = await fetch(`${ATEL_PLATFORM}/trade/v1/order/${orderId}/accept`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(signedRequest),
-          signal: AbortSignal.timeout(10000), // 10秒超时
-        });
-        
-        log({ event: 'order_accept_response', orderId, status: acceptResp.status, ok: acceptResp.ok });
-        
-        if (acceptResp.ok) {
+
+      // Call platform API to accept (retry up to 3 times for transient RPC failures)
+      let acceptOk = false;
+      let lastError = '';
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          const timestamp = new Date().toISOString();
+          const payload = {};
+          const signPayload = { did: id.did, timestamp, payload };
+          const signature = sign(signPayload, id.secretKey);
+          const signedRequest = { did: id.did, timestamp, signature, payload };
+
+          log({ event: 'order_accept_calling_api', orderId, platform: ATEL_PLATFORM, attempt: attempt + 1 });
+
+          const acceptResp = await fetch(`${ATEL_PLATFORM}/trade/v1/order/${orderId}/accept`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(signedRequest),
+            signal: AbortSignal.timeout(30000), // 30s timeout (escrow tx can take 10-15s)
+          });
+
+          log({ event: 'order_accept_response', orderId, status: acceptResp.status, ok: acceptResp.ok, attempt: attempt + 1 });
+
+          if (acceptResp.ok) {
+            acceptOk = true;
+            break;
+          }
+
+          const errBody = await acceptResp.text();
+          lastError = errBody;
+          log({ event: 'order_accept_failed', orderId, error: errBody, status: acceptResp.status, attempt: attempt + 1 });
+
+          // Retry if server hints it's a transient failure
+          const shouldRetry = errBody.includes('retry') || errBody.includes('RPC') || errBody.includes('balance check failed');
+          if (!shouldRetry || attempt >= 2) break;
+          log({ event: 'order_accept_retrying', orderId, waitMs: 5000 });
+          await new Promise(r => setTimeout(r, 5000));
+        } catch (err) {
+          lastError = err.message;
+          log({ event: 'order_accept_error', orderId, error: err.message, attempt: attempt + 1 });
+          if (attempt >= 2) break;
+          await new Promise(r => setTimeout(r, 5000));
+        }
+      }
+
+      if (acceptOk) {
+        try {
           log({ event: 'order_accepted', orderId });
           res.json({ status: 'accepted', orderId });
 
@@ -2243,15 +2327,12 @@ async function cmdStart(port) {
               log({ event: 'milestone_auto_approve_error', orderId, error: e.message });
             }
           }, 2000);
-        } else {
-          const error = await acceptResp.text();
-          log({ event: 'order_accept_failed', orderId, error, status: acceptResp.status });
-          res.status(500).json({ error: 'accept failed: ' + error });
+        } catch (e) {
+          log({ event: 'milestone_auto_approve_outer_error', orderId, error: e.message });
         }
-      } catch (err) {
-        log({ event: 'order_accept_error', orderId, error: err.message, stack: err.stack });
-        console.error('[ERROR] Order accept failed:', err);
-        res.status(500).json({ error: err.message });
+      } else {
+        log({ event: 'order_accept_gave_up', orderId, lastError });
+        res.status(500).json({ error: 'accept failed after retries: ' + lastError });
       }
       return;
     }
@@ -2345,25 +2426,31 @@ async function cmdStart(port) {
       return;
     }
 
-    // Milestone events
+    // Milestone events (helpers defined above, shared with /atel/v1/result handler)
     if (event === 'milestone_submitted') {
       const { orderId, milestoneIndex, resultSummary, submitCount } = payload;
-      log({
-        event: 'milestone_submitted_notification',
-        orderId,
-        milestoneIndex,
-        resultSummary: resultSummary || '(no summary)',
-        submitCount,
-        message: `M${milestoneIndex} submitted. Review the content and verify:`,
-        action: `atel milestone-verify ${orderId} ${milestoneIndex} --pass   (or --reject "reason")`,
-      });
-      // Print prominently so the agent/user actually sees the content
-      console.log(`\n📋 [Milestone M${milestoneIndex} submitted for ${orderId}]`);
-      console.log(`   Content: ${resultSummary || '(no summary provided)'}`);
-      console.log(`   Attempt: ${submitCount || 1}/3`);
-      console.log(`   Action:  atel milestone-verify ${orderId} ${milestoneIndex} --pass`);
-      console.log(`            atel milestone-verify ${orderId} ${milestoneIndex} --reject "reason"\n`);
+      log({ event: 'milestone_submitted_notification', orderId, milestoneIndex, resultSummary: resultSummary || '(no summary)', submitCount });
+      console.log(`\n📋 M${milestoneIndex} submitted for ${orderId}. Agent reviewing...`);
       res.json({ status: 'received', event });
+      // Requester Agent: auto-review using agent's own brain (async callback)
+      setTimeout(async () => {
+        try {
+          const ms = await getMilestoneInfo(orderId);
+          if (!ms || !ms.milestones) return;
+          const m = ms.milestones[milestoneIndex];
+          if (!m) return;
+          const orderDesc = ms.description || orderId;
+          const submittedContent = m.result_summary || resultSummary || '(no content)';
+          const prompt = `You are an AI Agent reviewing a milestone submission.\n\nOrder: ${orderDesc}\nMilestone M${milestoneIndex}: ${m.description || m.title}\nSubmitted content: ${submittedContent}\n\nEvaluate: Does the submission adequately fulfill the milestone goal?\nReply with EXACTLY one of:\n- PASS\n- REJECT: <specific reason>`;
+          console.log(`\n🔍 Reviewing M${milestoneIndex} for ${orderId}...`);
+          await agentExecute(prompt, `review-${orderId}-${milestoneIndex}`, { orderId, milestoneIndex, type: 'verify' });
+        } catch (e) {
+          // Fallback: auto-pass if agent brain unavailable
+          log({ event: 'auto_review_fallback', orderId, milestone: milestoneIndex, error: e.message });
+          console.log(`\n✅ Auto-pass M${milestoneIndex} (review fallback)`);
+          await autoMilestoneVerify(orderId, milestoneIndex, true);
+        }
+      }, 3000);
       return;
     }
 
@@ -2371,8 +2458,23 @@ async function cmdStart(port) {
       const { orderId, milestoneIndex, currentMilestone, totalMilestones, allComplete } = payload;
       if (allComplete) {
         log({ event: 'all_milestones_complete', orderId, message: 'Settlement in progress' });
+        console.log(`\n🎉 All milestones complete for ${orderId}. Settlement in progress.`);
       } else {
-        log({ event: 'milestone_verified_notification', orderId, milestoneIndex, next: currentMilestone, message: `M${milestoneIndex} verified. Ready to submit M${currentMilestone}` });
+        log({ event: 'milestone_verified_notification', orderId, milestoneIndex, next: currentMilestone });
+        console.log(`\n✅ M${milestoneIndex} verified for ${orderId}. Working on M${currentMilestone}...`);
+        // Auto-submit next milestone using agent's own brain (async callback)
+        setTimeout(async () => {
+          try {
+            const ms = await getMilestoneInfo(orderId);
+            if (!ms || !ms.milestones) return;
+            const nextM = ms.milestones[currentMilestone];
+            if (!nextM) return;
+            const orderDesc = ms.description || orderId;
+            const prompt = `You are an AI Agent executing a paid task.\n\nOrder: ${orderDesc}\nMilestone M${currentMilestone}: ${nextM.description || nextM.title}\n\nPrevious milestones have been completed and approved. Now complete this milestone. Provide a thorough, detailed deliverable. Output ONLY the deliverable content.`;
+            console.log(`\n🤖 Working on M${currentMilestone} for ${orderId}...`);
+            await agentExecute(prompt, `milestone-${orderId}-${currentMilestone}`, { orderId, milestoneIndex: currentMilestone, type: 'submit' });
+          } catch (e) { log({ event: 'auto_milestone_next_error', orderId, error: e.message }); }
+        }, 3000);
       }
       res.json({ status: 'received', event });
       return;
@@ -2380,8 +2482,22 @@ async function cmdStart(port) {
 
     if (event === 'milestone_rejected') {
       const { orderId, milestoneIndex, rejectReason } = payload;
-      log({ event: 'milestone_rejected_notification', orderId, milestoneIndex, rejectReason, message: 'Resubmit with improvements' });
+      log({ event: 'milestone_rejected_notification', orderId, milestoneIndex, rejectReason });
+      console.log(`\n❌ M${milestoneIndex} rejected for ${orderId}: ${rejectReason}. Improving...`);
       res.json({ status: 'received', event });
+      // Auto-resubmit with improvements using agent's own brain (async callback)
+      setTimeout(async () => {
+        try {
+          const ms = await getMilestoneInfo(orderId);
+          if (!ms || !ms.milestones) return;
+          const m = ms.milestones[milestoneIndex];
+          if (!m) return;
+          const orderDesc = ms.description || orderId;
+          const prompt = `You are an AI Agent. Your previous submission was REJECTED.\n\nOrder: ${orderDesc}\nMilestone M${milestoneIndex}: ${m.description || m.title}\nRejection reason: ${rejectReason}\n\nImprove your work based on the feedback. Output ONLY the improved deliverable.`;
+          console.log(`\n🔄 Improving M${milestoneIndex} for ${orderId}...`);
+          await agentExecute(prompt, `milestone-${orderId}-${milestoneIndex}-retry`, { orderId, milestoneIndex, type: 'submit' });
+        } catch (e) { log({ event: 'auto_milestone_resubmit_error', orderId, error: e.message }); }
+      }, 3000);
       return;
     }
 
@@ -2392,6 +2508,68 @@ async function cmdStart(port) {
       return;
     }
 
+    // Requester: order was accepted by executor (USDC locked) → auto-approve plan
+    if (event === 'order_accepted' && payload.executorDid) {
+      const { orderId, executorDid, escrowTx } = payload;
+      log({ event: 'order_accepted_by_executor', orderId, executorDid, escrowTx });
+      console.log(`\n📋 Order ${orderId} accepted! Auto-approving milestone plan...`);
+      res.json({ status: 'received', event });
+      // Auto-approve milestone plan (non-blocking)
+      setTimeout(async () => {
+        try {
+          for (let wait = 0; wait < 10; wait++) {
+            await new Promise(r => setTimeout(r, 3000));
+            const ms = await getMilestoneInfo(orderId);
+            if (ms && ms.totalMilestones > 0) {
+              const ts = new Date().toISOString();
+              const pl = { approved: true };
+              const sig = sign({ did: id.did, timestamp: ts, payload: pl }, id.secretKey);
+              const fbResp = await fetch(`${PLATFORM_URL}/trade/v1/order/${orderId}/milestones/feedback`, {
+                method: 'POST', headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ did: id.did, timestamp: ts, signature: sig, payload: pl }),
+                signal: AbortSignal.timeout(10000),
+              });
+              log({ event: 'requester_auto_approved_plan', orderId, ok: fbResp.ok });
+              break;
+            }
+          }
+        } catch (e) { log({ event: 'requester_auto_approve_error', orderId, error: e.message }); }
+      }, 2000);
+      return;
+    }
+
+    // Both parties: milestone plan confirmed, execution started
+    if (event === 'milestone_plan_confirmed') {
+      const { orderId, message } = payload;
+      log({ event: 'milestone_plan_confirmed', orderId, message });
+      console.log(`\n✅ Milestone plan confirmed for ${orderId}. Execution started.`);
+      res.json({ status: 'received', event });
+      // Executor: auto-submit M0 using agent's own brain (non-blocking, async callback)
+      if (message && message.includes('Submit milestone')) {
+        setTimeout(async () => {
+          try {
+            const ms = await getMilestoneInfo(orderId);
+            if (!ms || !ms.milestones || ms.milestones.length === 0) return;
+            const m0 = ms.milestones[0];
+            const orderDesc = ms.description || orderId;
+            const prompt = `You are an AI Agent executing a paid task.\n\nOrder: ${orderDesc}\nMilestone M0: ${m0.description || m0.title}\n\nComplete this milestone. Provide a thorough, detailed deliverable. Output ONLY the deliverable content.`;
+            console.log(`\n🤖 Working on M0 for ${orderId}...`);
+            await agentExecute(prompt, `milestone-${orderId}-0`, { orderId, milestoneIndex: 0, type: 'submit' });
+          } catch (e) { log({ event: 'auto_milestone_0_error', orderId, error: e.message }); }
+        }, 3000);
+      }
+      return;
+    }
+
+    // Both parties: order settled, payment released
+    if (event === 'order_settled') {
+      const { orderId, message } = payload;
+      log({ event: 'order_settled_notification', orderId, message });
+      console.log(`\n💰 Order ${orderId} settled! ${message || 'Check: atel balance'}`);
+      res.json({ status: 'received', event });
+      return;
+    }
+
     // Unknown event type
     res.json({ status: 'ignored', event });
   });
@@ -2400,6 +2578,8 @@ async function cmdStart(port) {
   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; }
+
+    // Milestone auto-execution removed. Agent handles results via its own AI.
     const task = pendingTasks[taskId];
     const startTime = new Date(task.acceptedAt).getTime();
     const durationMs = Date.now() - startTime;
@@ -3276,7 +3456,14 @@ async function cmdStart(port) {
           body: JSON.stringify({ did: id.did }), signal: AbortSignal.timeout(5000),
         });
         if (!resp.ok) return;
-        const { requests } = await resp.json();
+        const data = await resp.json();
+        // Relay returns {messages: [{id, sender, message, createdAt}]}
+        // Each message.message contains {method, path, body}
+        const rawMessages = data.messages || data.requests || [];
+        const requests = rawMessages.map(m => {
+          const inner = m.message || m;
+          return typeof inner === 'string' ? JSON.parse(inner) : inner;
+        });
         for (const req of requests) {
           // Forward to local endpoint
           try {
@@ -3342,14 +3529,14 @@ async function cmdStart(port) {
   process.on('SIGINT', async () => { 
     heartbeat.stop();
     if (tunnelManager) await tunnelManager.stop();
-    if (builtinExecutor) await builtinExecutor.stop();
+    
     await endpoint.stop(); 
     process.exit(0); 
   });
   process.on('SIGTERM', async () => { 
     heartbeat.stop();
     if (tunnelManager) await tunnelManager.stop();
-    if (builtinExecutor) await builtinExecutor.stop();
+    
     await endpoint.stop(); 
     process.exit(0); 
   });
@@ -5441,14 +5628,32 @@ async function cmdFriendRequest(args) {
   };
   
   // Sign the request
-  const signedRequest = createMessage(request, id.secretKey);
+  const signedRequest = createMessage({ ...request, secretKey: id.secretKey });
   
-  // Try to send via P2P
+  // Try to send via P2P — look up registry for endpoint
   let sent = false;
   let error = null;
   
   try {
-    const result = await sendP2PMessage(targetDid, signedRequest);
+    // Resolve endpoint from registry
+    let endpoint = null;
+    try {
+      const resp = await fetch(`${REGISTRY_URL}/registry/v1/agent/${encodeURIComponent(targetDid)}`, { signal: AbortSignal.timeout(5000) });
+      if (resp.ok) {
+        const entry = await resp.json();
+        const candidates = entry.endpoint_candidates || [];
+        const direct = candidates.find(c => c.type === 'direct');
+        const relay = candidates.find(c => c.type === 'relay');
+        endpoint = direct?.url || relay?.url || entry.endpoint;
+      }
+    } catch (e) {
+      throw new Error(`Cannot find agent in registry: ${e.message}`);
+    }
+    if (!endpoint) throw new Error('Agent has no reachable endpoint');
+    
+    const hsManager = new HandshakeManager(id);
+    const client = new AgentClient(id);
+    await client.sendTask(endpoint, signedRequest, hsManager);
     sent = true;
   } catch (err) {
     error = err.message;
@@ -5538,7 +5743,7 @@ async function cmdFriendAccept(args) {
     }
   };
   
-  const signedMsg = createMessage(acceptMsg, id.secretKey);
+  const signedMsg = createMessage({ ...acceptMsg, secretKey: id.secretKey });
   
   try {
     await sendP2PMessage(request.from, signedMsg);
@@ -5604,7 +5809,7 @@ async function cmdFriendReject(args) {
     }
   };
   
-  const signedMsg = createMessage(rejectMsg, id.secretKey);
+  const signedMsg = createMessage({ ...rejectMsg, secretKey: id.secretKey });
   
   try {
     await sendP2PMessage(request.from, signedMsg);
@@ -5742,6 +5947,214 @@ async function cmdFriendStatus(args) {
   console.log('');
 }
 
+// ─── P2P Send Helper ────────────────────────────────────────────
+// Resolves DID → endpoint via registry, then sends a signed message.
+// Replaces the previously undefined sendP2PMessage.
+async function sendP2PMessage(targetDid, signedMsg) {
+  const id = loadIdentity();
+  if (!id) throw new Error('No identity found');
+
+  let endpoint = null;
+  try {
+    const resp = await fetch(`${REGISTRY_URL}/registry/v1/agent/${encodeURIComponent(targetDid)}`, { signal: AbortSignal.timeout(5000) });
+    if (resp.ok) {
+      const entry = await resp.json();
+      const candidates = entry.endpoint_candidates || [];
+      const direct = candidates.find(c => c.type === 'direct');
+      const relay  = candidates.find(c => c.type === 'relay');
+      endpoint = direct?.url || relay?.url || entry.endpoint;
+    }
+  } catch (e) {
+    throw new Error(`Registry lookup failed for ${targetDid}: ${e.message}`);
+  }
+  if (!endpoint) throw new Error(`No reachable endpoint for ${targetDid}`);
+
+  const hsManager = new HandshakeManager(id);
+  const client    = new AgentClient(id);
+  return await client.sendTask(endpoint, signedMsg, hsManager);
+}
+
+// ─── Send Command (Rich Media P2P Messaging) ─────────────────────
+
+function showSendHelp() {
+  console.log(`
+atal send — Send a message (with optional rich media) to another agent
+
+Usage:
+  atel send <did|alias|endpoint> "message text"
+  atel send <did> "look at this" --image ./photo.jpg
+  atel send <did> "here is the file" --file ./report.pdf
+  atel send <did> "listen" --audio ./voice.mp3
+  atel send <did> "watch this" --video ./clip.mp4
+
+Flags:
+  --image <path>   Attach image (jpg/png/gif/webp, max 10MB, up to 9)
+  --file  <path>   Attach file  (pdf/zip/txt/json, max 100MB, up to 5)
+  --audio <path>   Attach audio (mp3/wav/ogg/m4a, max 50MB)
+  --video <path>   Attach video (mp4/webm/mov, max 500MB)
+  --json           Output result as JSON
+
+Notes:
+  By default, agents require a mutual friend relationship before accepting
+  P2P messages. If you get a NOT_FRIEND error, run:
+    atel friend request <did>
+  and ask the other side to accept with:
+    atel friend accept <request-id>
+
+  To disable the friend requirement on your own agent, set in policy.json:
+    { "relationshipPolicy": { "defaultMode": "open" } }
+
+Examples:
+  atel send did:atel:ed25519:ABC "Hello!"
+  atel send @alice "Check this" --image ./screenshot.png
+  atel send did:atel:ed25519:ABC "Report" --file ./q1.pdf
+`);
+}
+
+async function cmdSend(args) {
+  const target  = args._[0];
+  const text    = args._[1] || '';
+  const isJson  = rawArgs.includes('--json');
+
+  if (!target) { showSendHelp(); process.exit(1); }
+
+  const id = loadIdentity();
+  if (!id) { console.error('No identity found. Run: atel init'); process.exit(1); }
+
+  // Parse attachment flags
+  const attachmentFlags = parseAttachmentFlags(rawArgs);
+  const hasAttachments  = attachmentFlags.images.length > 0 ||
+                          attachmentFlags.files.length  > 0 ||
+                          attachmentFlags.audios.length > 0 ||
+                          attachmentFlags.videos.length > 0;
+
+  if (!text && !hasAttachments) {
+    console.error('Error: message text or at least one attachment is required');
+    showSendHelp(); process.exit(1);
+  }
+
+  // Build payload
+  const msgId   = `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  const payload = {
+    action:    'general',   // broad compatibility with all SDK versions
+    msgType:   'message',   // identifies this as a p2p chat message
+    msgId,
+    text,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Upload attachments
+  if (hasAttachments) {
+    try {
+      if (!isJson) process.stderr.write('Uploading attachments...\n');
+      const processed = await processAttachments(attachmentFlags, id.did, msgId);
+      if (processed.images.length     > 0) payload.images      = processed.images;
+      if (processed.attachments.length > 0) payload.attachments = processed.attachments;
+      if (!isJson) {
+        const total = (processed.images.length + processed.attachments.length);
+        process.stderr.write(`  ✓ ${total} attachment(s) ready\n`);
+      }
+    } catch (err) {
+      console.error(`Attachment upload failed: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Resolve target → endpoint + remoteDid
+  let remoteEndpoint = target;
+  let remoteDid;
+
+  // Resolve @alias
+  try { const r = resolveDID(target); if (r !== target) remoteEndpoint = r; } catch (_) {}
+
+  if (!remoteEndpoint.startsWith('http')) {
+    // Registry lookup
+    let entry;
+    try {
+      const resp = await fetch(`${REGISTRY_URL}/registry/v1/agent/${encodeURIComponent(remoteEndpoint)}`, { signal: AbortSignal.timeout(5000) });
+      if (resp.ok) entry = await resp.json();
+    } catch (_) {}
+    if (!entry) {
+      const regClient = new RegistryClient({ registryUrl: REGISTRY_URL });
+      const results = await regClient.search({ type: remoteEndpoint, limit: 1 });
+      if (results.length > 0) entry = results[0];
+    }
+    if (!entry) { console.error(`Agent not found: ${target}`); process.exit(1); }
+    remoteDid = entry.did;
+    const candidates = entry.endpoint_candidates || [];
+    const direct = candidates.find(c => c.type === 'direct');
+    const relay  = candidates.find(c => c.type === 'relay');
+    remoteEndpoint = direct?.url || relay?.url || entry.endpoint;
+  } else {
+    remoteDid = target.startsWith('did:') ? target : undefined;
+    // Try to get remoteDid from handshake cache for direct endpoints
+    if (!remoteDid) {
+      try {
+        const tmpHs = new HandshakeManager(id);
+        const session = await tmpHs.getOrCreate(remoteEndpoint);
+        if (session?.remoteDid) remoteDid = session.remoteDid;
+      } catch (_) {}
+    }
+  }
+
+  if (!remoteEndpoint) {
+    console.error(`No reachable endpoint for: ${target}`);
+    process.exit(1);
+  }
+
+  // Send
+  try {
+    const hsManager = new HandshakeManager(id);
+    const client    = new AgentClient(id);
+    const msg       = createMessage({ type: 'task', from: id.did, to: remoteDid || remoteEndpoint, payload, secretKey: id.secretKey });
+    const result    = await client.sendTask(remoteEndpoint, msg, hsManager);
+
+    // Surface friendly errors
+    const inner = result?.result;
+    if (inner?.code === 'NOT_FRIEND' || inner?.error?.includes('NOT_FRIEND') || inner?.error?.includes('not a friend')) {
+      if (isJson) {
+        console.log(JSON.stringify({ status: 'error', code: 'NOT_FRIEND', message: inner.error, hint: `Run: atel friend request ${remoteDid || target}` }));
+      } else {
+        console.error(`✗ Message blocked: the recipient requires a friend relationship.`);
+        console.error(`  Run: atel friend request ${remoteDid || target}`);
+        console.error(`  Then ask them to: atel friend accept <request-id>`);
+      }
+      process.exit(1);
+    }
+    if (inner?.status === 'rejected') {
+      if (isJson) {
+        console.log(JSON.stringify({ status: 'error', message: inner.error || 'Message rejected', result }));
+      } else {
+        console.error(`✗ Message rejected: ${inner.error || 'unknown reason'}`);
+      }
+      process.exit(1);
+    }
+
+    if (isJson) {
+      console.log(JSON.stringify({ status: 'sent', msgId, to: remoteDid || remoteEndpoint, attachments: (payload.images?.length || 0) + (payload.attachments?.length || 0), result }, null, 2));
+    } else {
+      console.log(`✓ Message sent to ${remoteDid || remoteEndpoint}`);
+      if (payload.images?.length)      console.log(`  Images:      ${payload.images.length}`);
+      if (payload.attachments?.length) console.log(`  Attachments: ${payload.attachments.length}`);
+    }
+  } catch (err) {
+    if (isJson) {
+      console.log(JSON.stringify({ status: 'error', message: err.message }));
+    } else {
+      // Surface specific known errors in human-readable form
+      if (err.message?.includes('fetch failed') || err.message?.includes('ECONNREFUSED')) {
+        console.error(`✗ Cannot reach agent at ${remoteEndpoint}`);
+        console.error(`  The agent may be offline or behind a firewall.`);
+      } else if (err.message?.includes('401') || err.message?.includes('Unauthorized')) {
+        console.error(`✗ Authentication failed — try: atel handshake ${remoteEndpoint}`);
+      } else {
+        console.error(`✗ Send failed: ${err.message}`);
+      }
+    }
+    process.exit(1);
+  }
+}
+
 // ─── Temporary Session Commands ──────────────────────────────────
 
 async function cmdTempAllow(args) {
@@ -6212,6 +6625,14 @@ const commands = {
     console.error('  status [--json]');
     process.exit(1);
   },
+  // Send (Rich Media P2P Message)
+  send: () => {
+    if (rawArgs.includes('--help') || rawArgs.includes('-h') || args.length === 0) {
+      showSendHelp();
+      process.exit(0);
+    }
+    return cmdSend({ _: args, json: rawArgs.includes('--json') });
+  },
   // Alias System
   alias: () => {
     const subCmd = args[0];
@@ -6248,6 +6669,7 @@ Protocol Commands:
   register [name] [caps] [endpoint]    Register on public registry (caps: "type1:price1,type2:price2" or "type1,type2" for free)
   search <capability>                  Search registry for agents (shows pricing info)
   handshake <endpoint> [did]           Handshake with remote agent
+  send <target> "text" [--image/--file/--audio/--video <path>]  Send P2P message with optional rich media
   task <target> <json>                 Delegate task (auto trust check)
   result <taskId> <json>               Submit execution result (from executor)
   check <did> [risk]                   Check agent trust (risk: low|medium|high|critical)