@lawreneliang/atel-sdk 0.4.2 → 0.4.4

package/bin/atel.mjs

@@ -3,17 +3,12 @@
 /**
  * ATEL CLI — Command-line interface for ATEL SDK
  *
- * Async execution model:
- *   1. Receive task → security check → return accepted + taskId
- *   2. Forward to local executor (ATEL_EXECUTOR_URL)
- *   3. Executor completes → callback to atel
- *   4. Trace → Proof → on-chain anchor
- *   5. Push result back to sender (encrypted)
- *
  * Commands:
  *   atel init [name]                    Create agent identity + default policy
- *   atel info                           Show identity, capabilities, policy
- *   atel start [port]                   Start endpoint (async execution)
+ *   atel info                           Show identity, capabilities, policy, network
+ *   atel start [port]                   Start endpoint (auto network + auto register)
+ *   atel setup [port]                   Network setup only (detect IP, UPnP, verify)
+ *   atel verify                         Verify port reachability
  *   atel inbox [count]                  Show received messages
  *   atel register [name] [caps] [url]   Register on public registry
  *   atel search <capability>            Search registry for agents
@@ -25,15 +20,10 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import {
-  AgentIdentity,
-  AgentEndpoint,
-  AgentClient,
-  HandshakeManager,
-  createMessage,
-  RegistryClient,
-  ExecutionTrace,
-  ProofGenerator,
-  SolanaAnchorProvider,
+  AgentIdentity, AgentEndpoint, AgentClient, HandshakeManager,
+  createMessage, RegistryClient, ExecutionTrace, ProofGenerator,
+  SolanaAnchorProvider, autoNetworkSetup, collectCandidates, connectToAgent,
+  discoverPublicIP, checkReachable,
 } from '@lawreneliang/atel-sdk';
 
 const ATEL_DIR = resolve(process.env.ATEL_DIR || '.atel');
@@ -43,134 +33,43 @@ const EXECUTOR_URL = process.env.ATEL_EXECUTOR_URL || '';
 const INBOX_FILE = resolve(ATEL_DIR, 'inbox.jsonl');
 const POLICY_FILE = resolve(ATEL_DIR, 'policy.json');
 const TASKS_FILE = resolve(ATEL_DIR, 'tasks.json');
+const NETWORK_FILE = resolve(ATEL_DIR, 'network.json');
 
-// ─── Default Policy ──────────────────────────────────────────────
-
-const DEFAULT_POLICY = {
-  rateLimit: 60,           // max tasks per minute
-  maxPayloadBytes: 1048576, // 1MB
-  maxConcurrent: 10,
-  allowedDIDs: [],          // empty = allow all
-  blockedDIDs: [],
-};
+const DEFAULT_POLICY = { rateLimit: 60, maxPayloadBytes: 1048576, maxConcurrent: 10, allowedDIDs: [], blockedDIDs: [] };
 
 // ─── Helpers ─────────────────────────────────────────────────────
 
-function ensureDir() {
-  if (!existsSync(ATEL_DIR)) mkdirSync(ATEL_DIR, { recursive: true });
-}
+function ensureDir() { if (!existsSync(ATEL_DIR)) mkdirSync(ATEL_DIR, { recursive: true }); }
+function log(event) { ensureDir(); appendFileSync(INBOX_FILE, JSON.stringify(event) + '\n'); console.log(JSON.stringify(event)); }
 
-function log(event) {
-  ensureDir();
-  appendFileSync(INBOX_FILE, JSON.stringify(event) + '\n');
-  console.log(JSON.stringify(event));
-}
+function saveIdentity(id) { ensureDir(); writeFileSync(IDENTITY_FILE, JSON.stringify({ agent_id: id.agent_id, did: id.did, publicKey: Buffer.from(id.publicKey).toString('hex'), secretKey: Buffer.from(id.secretKey).toString('hex') }, null, 2)); }
+function loadIdentity() { if (!existsSync(IDENTITY_FILE)) return null; const d = JSON.parse(readFileSync(IDENTITY_FILE, 'utf-8')); return new AgentIdentity({ agent_id: d.agent_id, publicKey: Uint8Array.from(Buffer.from(d.publicKey, 'hex')), secretKey: Uint8Array.from(Buffer.from(d.secretKey, 'hex')) }); }
+function requireIdentity() { const id = loadIdentity(); if (!id) { console.error('No identity. Run: atel init'); process.exit(1); } return id; }
 
-function saveIdentity(identity) {
-  ensureDir();
-  writeFileSync(IDENTITY_FILE, JSON.stringify({
-    agent_id: identity.agent_id,
-    did: identity.did,
-    publicKey: Buffer.from(identity.publicKey).toString('hex'),
-    secretKey: Buffer.from(identity.secretKey).toString('hex'),
-  }, null, 2));
-}
+function loadCapabilities() { const f = resolve(ATEL_DIR, 'capabilities.json'); if (!existsSync(f)) return []; try { return JSON.parse(readFileSync(f, 'utf-8')); } catch { return []; } }
+function saveCapabilities(c) { ensureDir(); writeFileSync(resolve(ATEL_DIR, 'capabilities.json'), JSON.stringify(c, null, 2)); }
+function loadPolicy() { if (!existsSync(POLICY_FILE)) return { ...DEFAULT_POLICY }; try { return { ...DEFAULT_POLICY, ...JSON.parse(readFileSync(POLICY_FILE, 'utf-8')) }; } catch { return { ...DEFAULT_POLICY }; } }
+function savePolicy(p) { ensureDir(); writeFileSync(POLICY_FILE, JSON.stringify(p, null, 2)); }
+function loadTasks() { if (!existsSync(TASKS_FILE)) return {}; try { return JSON.parse(readFileSync(TASKS_FILE, 'utf-8')); } catch { return {}; } }
+function saveTasks(t) { ensureDir(); writeFileSync(TASKS_FILE, JSON.stringify(t, null, 2)); }
+function loadNetwork() { if (!existsSync(NETWORK_FILE)) return null; try { return JSON.parse(readFileSync(NETWORK_FILE, 'utf-8')); } catch { return null; } }
+function saveNetwork(n) { ensureDir(); writeFileSync(NETWORK_FILE, JSON.stringify(n, null, 2)); }
 
-function loadIdentity() {
-  if (!existsSync(IDENTITY_FILE)) return null;
-  const data = JSON.parse(readFileSync(IDENTITY_FILE, 'utf-8'));
-  return new AgentIdentity({
-    agent_id: data.agent_id,
-    publicKey: Uint8Array.from(Buffer.from(data.publicKey, 'hex')),
-    secretKey: Uint8Array.from(Buffer.from(data.secretKey, 'hex')),
-  });
-}
-
-function requireIdentity() {
-  const id = loadIdentity();
-  if (!id) { console.error('No identity found. Run: atel init'); process.exit(1); }
-  return id;
-}
-
-function loadCapabilities() {
-  const f = resolve(ATEL_DIR, 'capabilities.json');
-  if (!existsSync(f)) return [];
-  try { return JSON.parse(readFileSync(f, 'utf-8')); } catch { return []; }
-}
-
-function saveCapabilities(caps) {
-  ensureDir();
-  writeFileSync(resolve(ATEL_DIR, 'capabilities.json'), JSON.stringify(caps, null, 2));
-}
-
-function loadPolicy() {
-  if (!existsSync(POLICY_FILE)) return { ...DEFAULT_POLICY };
-  try { return { ...DEFAULT_POLICY, ...JSON.parse(readFileSync(POLICY_FILE, 'utf-8')) }; } catch { return { ...DEFAULT_POLICY }; }
-}
-
-function savePolicy(policy) {
-  ensureDir();
-  writeFileSync(POLICY_FILE, JSON.stringify(policy, null, 2));
-}
-
-function loadTasks() {
-  if (!existsSync(TASKS_FILE)) return {};
-  try { return JSON.parse(readFileSync(TASKS_FILE, 'utf-8')); } catch { return {}; }
-}
-
-function saveTasks(tasks) {
-  ensureDir();
-  writeFileSync(TASKS_FILE, JSON.stringify(tasks, null, 2));
-}
-
-// ─── Policy Enforcement ──────────────────────────────────────────
+// ─── Policy Enforcer ─────────────────────────────────────────────
 
 class PolicyEnforcer {
-  constructor(policy) {
-    this.policy = policy;
-    this.requestLog = [];  // timestamps of recent requests per DID
-    this.activeTasks = 0;
-  }
-
+  constructor(policy) { this.policy = policy; this.requestLog = []; this.activeTasks = 0; }
   check(message) {
-    const p = this.policy;
-    const fromDid = message.from;
-    const payload = message.payload || {};
-    const payloadSize = JSON.stringify(payload).length;
-
-    // 1. Blocked DID
-    if (p.blockedDIDs.length > 0 && p.blockedDIDs.includes(fromDid)) {
-      return { allowed: false, reason: `DID ${fromDid} is blocked` };
-    }
-
-    // 2. Allowed DID whitelist (empty = allow all)
-    if (p.allowedDIDs.length > 0 && !p.allowedDIDs.includes(fromDid)) {
-      return { allowed: false, reason: `DID ${fromDid} is not in allowlist` };
-    }
-
-    // 3. Rate limit
-    const now = Date.now();
-    const windowMs = 60000;
-    this.requestLog = this.requestLog.filter(t => now - t < windowMs);
-    if (this.requestLog.length >= p.rateLimit) {
-      return { allowed: false, reason: `Rate limit exceeded (${p.rateLimit}/min)` };
-    }
-
-    // 4. Payload size
-    if (payloadSize > p.maxPayloadBytes) {
-      return { allowed: false, reason: `Payload too large (${payloadSize} > ${p.maxPayloadBytes} bytes)` };
-    }
-
-    // 5. Concurrent tasks
-    if (this.activeTasks >= p.maxConcurrent) {
-      return { allowed: false, reason: `Max concurrent tasks reached (${p.maxConcurrent})` };
-    }
-
-    // Record this request
+    const p = this.policy, from = message.from, size = JSON.stringify(message.payload || {}).length, now = Date.now();
+    if (p.blockedDIDs.length > 0 && p.blockedDIDs.includes(from)) return { allowed: false, reason: `DID blocked` };
+    if (p.allowedDIDs.length > 0 && !p.allowedDIDs.includes(from)) return { allowed: false, reason: `DID not in allowlist` };
+    this.requestLog = this.requestLog.filter(t => now - t < 60000);
+    if (this.requestLog.length >= p.rateLimit) return { allowed: false, reason: `Rate limit (${p.rateLimit}/min)` };
+    if (size > p.maxPayloadBytes) return { allowed: false, reason: `Payload too large (${size} > ${p.maxPayloadBytes})` };
+    if (this.activeTasks >= p.maxConcurrent) return { allowed: false, reason: `Max concurrent (${p.maxConcurrent})` };
     this.requestLog.push(now);
     return { allowed: true };
   }
-
   taskStarted() { this.activeTasks++; }
   taskFinished() { this.activeTasks = Math.max(0, this.activeTasks - 1); }
 }
@@ -178,20 +77,14 @@ class PolicyEnforcer {
 // ─── On-chain Anchoring ──────────────────────────────────────────
 
 async function anchorOnChain(traceRoot, metadata) {
-  const solanaKey = process.env.ATEL_SOLANA_PRIVATE_KEY;
-  if (!solanaKey) return null;
+  const key = process.env.ATEL_SOLANA_PRIVATE_KEY;
+  if (!key) return null;
   try {
-    const solana = new SolanaAnchorProvider({
-      rpcUrl: process.env.ATEL_SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com',
-      privateKey: solanaKey,
-    });
-    const record = await solana.anchor(traceRoot, metadata);
-    log({ event: 'proof_anchored', chain: 'solana', txHash: record.txHash, block: record.blockNumber, trace_root: traceRoot });
-    return record;
-  } catch (e) {
-    log({ event: 'anchor_failed', chain: 'solana', error: e.message });
-    return null;
-  }
+    const s = new SolanaAnchorProvider({ rpcUrl: process.env.ATEL_SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com', privateKey: key });
+    const r = await s.anchor(traceRoot, metadata);
+    log({ event: 'proof_anchored', chain: 'solana', txHash: r.txHash, block: r.blockNumber, trace_root: traceRoot });
+    return r;
+  } catch (e) { log({ event: 'anchor_failed', chain: 'solana', error: e.message }); return null; }
 }
 
 // ─── Commands ────────────────────────────────────────────────────
@@ -201,26 +94,38 @@ async function cmdInit(agentId) {
   const identity = new AgentIdentity({ agent_id: name });
   saveIdentity(identity);
   savePolicy(DEFAULT_POLICY);
-  console.log(JSON.stringify({
-    status: 'created',
-    agent_id: identity.agent_id,
-    did: identity.did,
-    policy: POLICY_FILE,
-    next: 'Run: atel register [name] [capabilities] [endpoint]',
-  }, null, 2));
+  console.log(JSON.stringify({ status: 'created', agent_id: identity.agent_id, did: identity.did, policy: POLICY_FILE, next: 'Run: atel start [port] — auto-configures network and registers' }, null, 2));
 }
 
 async function cmdInfo() {
   const id = requireIdentity();
-  const caps = loadCapabilities();
-  const policy = loadPolicy();
-  console.log(JSON.stringify({
-    agent_id: id.agent_id,
-    did: id.did,
-    capabilities: caps,
-    policy,
-    executor: EXECUTOR_URL || 'not configured (set ATEL_EXECUTOR_URL)',
-  }, null, 2));
+  console.log(JSON.stringify({ agent_id: id.agent_id, did: id.did, capabilities: loadCapabilities(), policy: loadPolicy(), network: loadNetwork(), executor: EXECUTOR_URL || 'not configured' }, null, 2));
+}
+
+async function cmdSetup(port) {
+  const p = parseInt(port || '3100');
+  console.log(JSON.stringify({ event: 'network_setup', port: p }));
+  const net = await autoNetworkSetup(p);
+  for (const step of net.steps) console.log(JSON.stringify({ event: 'step', message: step }));
+  if (net.endpoint) {
+    saveNetwork({ publicIP: net.publicIP, port: p, endpoint: net.endpoint, upnp: net.upnpSuccess, reachable: net.reachable, configuredAt: new Date().toISOString() });
+    console.log(JSON.stringify({ status: 'ready', endpoint: net.endpoint }));
+  } else if (net.publicIP) {
+    const ep = `http://${net.publicIP}:${p}`;
+    saveNetwork({ publicIP: net.publicIP, port: p, endpoint: ep, upnp: false, reachable: false, needsManualPortForward: true, configuredAt: new Date().toISOString() });
+    console.log(JSON.stringify({ status: 'needs_port_forward', publicIP: net.publicIP, port: p, instruction: `Forward external TCP port ${p} to this machine's port ${p} on your router. Then run: atel verify` }));
+  } else {
+    console.log(JSON.stringify({ status: 'failed', error: 'Could not determine public IP' }));
+  }
+}
+
+async function cmdVerify() {
+  const net = loadNetwork();
+  if (!net) { console.error('No network config. Run: atel setup'); process.exit(1); }
+  console.log(JSON.stringify({ event: 'verifying', ip: net.publicIP, port: net.port }));
+  const result = await verifyPortReachable(net.publicIP, net.port);
+  console.log(JSON.stringify({ status: result.reachable ? 'reachable' : 'not_reachable', detail: result.detail }));
+  if (result.reachable) { net.reachable = true; net.needsManualPortForward = false; saveNetwork(net); }
 }
 
 async function cmdStart(port) {
@@ -231,193 +136,124 @@ async function cmdStart(port) {
   const policy = loadPolicy();
   const enforcer = new PolicyEnforcer(policy);
   const pendingTasks = loadTasks();
+
+  // ── Network: collect candidates ──
+  let networkConfig = loadNetwork();
+  if (!networkConfig) {
+    log({ event: 'network_setup', status: 'auto-detecting' });
+    networkConfig = await autoNetworkSetup(p);
+    for (const step of networkConfig.steps) log({ event: 'network_step', message: step });
+    delete networkConfig.steps;
+    saveNetwork(networkConfig);
+  } else {
+    log({ event: 'network_loaded', candidates: networkConfig.candidates.length });
+  }
+
+  // ── Start endpoint ──
   const endpoint = new AgentEndpoint(id, { port: p, host: '0.0.0.0' });
 
-  // Result callback endpoint: POST /atel/v1/result
-  // Executor calls this when done
+  // Result callback: POST /atel/v1/result (executor calls this when done)
   endpoint.app?.post?.('/atel/v1/result', async (req, res) => {
     const { taskId, result, success } = req.body || {};
-    if (!taskId || !pendingTasks[taskId]) {
-      res.status(404).json({ error: 'Unknown taskId' });
-      return;
-    }
-
+    if (!taskId || !pendingTasks[taskId]) { res.status(404).json({ error: 'Unknown taskId' }); return; }
     const task = pendingTasks[taskId];
     enforcer.taskFinished();
 
-    // Complete the trace
     const trace = new ExecutionTrace(taskId, id);
-    trace.append('TASK_ACCEPTED', { from: task.from, action: task.action, payload: task.payload });
+    trace.append('TASK_ACCEPTED', { from: task.from, action: task.action });
     trace.append('TASK_FORWARDED', { executor_url: EXECUTOR_URL });
     trace.append('TASK_RESULT', { success: success !== false, result });
+    if (success !== false) trace.finalize(typeof result === 'object' ? result : { result });
+    else trace.fail(new Error(result?.error || 'Execution failed'));
 
-    if (success !== false) {
-      trace.finalize(typeof result === 'object' ? result : { result });
-    } else {
-      trace.fail(new Error(result?.error || 'Execution failed'));
-    }
-
-    // Generate proof
     const proofGen = new ProofGenerator(trace, id);
-    const proof = proofGen.generate(
-      capTypes.join(',') || 'no-policy',
-      `task-from-${task.from}`,
-      JSON.stringify(result),
-    );
-
-    // Anchor on-chain
-    const anchor = await anchorOnChain(proof.trace_root, {
-      proof_id: proof.proof_id,
-      task_from: task.from,
-      action: task.action,
-      taskId,
-    });
-
-    log({
-      event: 'task_completed',
-      taskId,
-      from: task.from,
-      action: task.action,
-      success: success !== false,
-      proof_id: proof.proof_id,
-      trace_root: proof.trace_root,
-      anchor_tx: anchor?.txHash || null,
-      timestamp: new Date().toISOString(),
-    });
-
-    // Push result back to sender (encrypted, via their endpoint)
+    const proof = proofGen.generate(capTypes.join(',') || 'no-policy', `task-from-${task.from}`, JSON.stringify(result));
+    const anchor = await anchorOnChain(proof.trace_root, { proof_id: proof.proof_id, task_from: task.from, action: task.action, taskId });
+
+    log({ event: 'task_completed', taskId, from: task.from, action: task.action, success: success !== false, proof_id: proof.proof_id, anchor_tx: anchor?.txHash || null, timestamp: new Date().toISOString() });
+
+    // Push result back to sender
     if (task.senderEndpoint) {
       try {
         const client = new AgentClient(id);
         const hsManager = new HandshakeManager(id);
         await client.handshake(task.senderEndpoint, hsManager, task.from);
-        const resultMsg = createMessage({
-          type: 'task-result',
-          from: id.did,
-          to: task.from,
-          payload: {
-            taskId,
-            status: success !== false ? 'completed' : 'failed',
-            result,
-            proof: { proof_id: proof.proof_id, trace_root: proof.trace_root },
-            anchor: anchor ? { chain: 'solana', txHash: anchor.txHash } : null,
-          },
-          secretKey: id.secretKey,
-        });
-        await client.sendTask(task.senderEndpoint, resultMsg, hsManager);
-        log({ event: 'result_pushed', taskId, to: task.from, endpoint: task.senderEndpoint });
-      } catch (e) {
-        log({ event: 'result_push_failed', taskId, to: task.from, error: e.message });
-      }
+        const msg = createMessage({ type: 'task-result', from: id.did, to: task.from, payload: { taskId, status: success !== false ? 'completed' : 'failed', result, proof: { proof_id: proof.proof_id, trace_root: proof.trace_root }, anchor: anchor ? { chain: 'solana', txHash: anchor.txHash } : null }, secretKey: id.secretKey });
+        await client.sendTask(task.senderEndpoint, msg, hsManager);
+        log({ event: 'result_pushed', taskId, to: task.from });
+      } catch (e) { log({ event: 'result_push_failed', taskId, error: e.message }); }
     }
 
-    // Cleanup
-    delete pendingTasks[taskId];
-    saveTasks(pendingTasks);
-
+    delete pendingTasks[taskId]; saveTasks(pendingTasks);
     res.json({ status: 'ok', proof_id: proof.proof_id, anchor_tx: anchor?.txHash || null });
   });
 
+  // Task handler
   endpoint.onTask(async (message, session) => {
     const payload = message.payload || {};
     const action = payload.action || payload.type || 'unknown';
 
-    // ── Policy enforcement ──
-    const policyCheck = enforcer.check(message);
-    if (!policyCheck.allowed) {
-      log({ event: 'task_rejected', from: message.from, action, reason: policyCheck.reason, timestamp: new Date().toISOString() });
-      return { status: 'rejected', error: policyCheck.reason };
-    }
+    // Policy check
+    const pc = enforcer.check(message);
+    if (!pc.allowed) { log({ event: 'task_rejected', from: message.from, action, reason: pc.reason, timestamp: new Date().toISOString() }); return { status: 'rejected', error: pc.reason }; }
 
-    // ── Capability boundary check ──
+    // Capability check
     if (capTypes.length > 0 && !capTypes.includes(action) && !capTypes.includes('general')) {
-      log({ event: 'task_rejected', from: message.from, action, reason: `Outside capability boundary: [${capTypes.join(', ')}]`, timestamp: new Date().toISOString() });
+      log({ event: 'task_rejected', from: message.from, action, reason: `Outside capability: [${capTypes.join(',')}]`, timestamp: new Date().toISOString() });
       return { status: 'rejected', error: `Action "${action}" outside capability boundary`, capabilities: capTypes };
     }
 
-    // ── Accept task (async) ──
     const taskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     enforcer.taskStarted();
 
-    // Look up sender's endpoint from registry for result push-back
+    // Lookup sender endpoint for result push-back
     let senderEndpoint = null;
-    try {
-      const regClient = new RegistryClient({ registryUrl: REGISTRY_URL });
-      const resp = await fetch(`${REGISTRY_URL}/registry/v1/agent/${encodeURIComponent(message.from)}`);
-      if (resp.ok) {
-        const entry = await resp.json();
-        senderEndpoint = entry.endpoint;
-      }
-    } catch { /* best effort */ }
-
-    pendingTasks[taskId] = {
-      from: message.from,
-      action,
-      payload,
-      senderEndpoint,
-      encrypted: !!session?.encrypted,
-      acceptedAt: new Date().toISOString(),
-    };
-    saveTasks(pendingTasks);
+    try { const r = await fetch(`${REGISTRY_URL}/registry/v1/agent/${encodeURIComponent(message.from)}`); if (r.ok) senderEndpoint = (await r.json()).endpoint; } catch {}
 
+    pendingTasks[taskId] = { from: message.from, action, payload, senderEndpoint, encrypted: !!session?.encrypted, acceptedAt: new Date().toISOString() };
+    saveTasks(pendingTasks);
     log({ event: 'task_accepted', taskId, from: message.from, action, encrypted: !!session?.encrypted, timestamp: new Date().toISOString() });
 
-    // ── Forward to executor ──
+    // Forward to executor or echo
     if (EXECUTOR_URL) {
-      try {
-        const execPayload = { taskId, from: message.from, action, payload, encrypted: !!session?.encrypted };
-        fetch(EXECUTOR_URL, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(execPayload),
-        }).catch(e => {
-          log({ event: 'executor_forward_failed', taskId, error: e.message });
-        });
-        // Don't await — async execution
-      } catch (e) {
-        log({ event: 'executor_forward_failed', taskId, error: e.message });
-      }
+      fetch(EXECUTOR_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ taskId, from: message.from, action, payload, encrypted: !!session?.encrypted }) }).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 {
-      // No executor configured — auto-complete with echo
+      // Echo mode
       enforcer.taskFinished();
       const trace = new ExecutionTrace(taskId, id);
       trace.append('TASK_ACCEPTED', { from: message.from, action, payload });
       const result = { status: 'no_executor', agent: id.agent_id, action, received_payload: payload };
-      trace.append('TASK_ECHO', { result });
-      trace.finalize(result);
+      trace.append('TASK_ECHO', { result }); trace.finalize(result);
       const proofGen = new ProofGenerator(trace, id);
       const proof = proofGen.generate(capTypes.join(',') || 'no-policy', `task-from-${message.from}`, JSON.stringify(result));
       const anchor = await anchorOnChain(proof.trace_root, { proof_id: proof.proof_id, task_from: message.from, action, taskId });
-      delete pendingTasks[taskId];
-      saveTasks(pendingTasks);
+      delete pendingTasks[taskId]; saveTasks(pendingTasks);
       log({ event: 'task_completed', taskId, from: message.from, action, mode: 'echo', proof_id: proof.proof_id, anchor_tx: anchor?.txHash || null, timestamp: new Date().toISOString() });
       return { status: 'completed', taskId, result, proof, anchor };
     }
-
-    // Return accepted immediately — result comes later via push-back
-    return { status: 'accepted', taskId, message: 'Task accepted. Result will be pushed to your endpoint when ready.' };
-  });
-
-  endpoint.onProof(async (message, session) => {
-    log({ event: 'proof_received', from: message.from, payload: message.payload, timestamp: new Date().toISOString() });
   });
 
-  // Also handle task-result messages (results pushed back from other agents)
-  endpoint.onMessage?.('task-result', async (message, session) => {
-    log({ event: 'task_result_received', from: message.from, payload: message.payload, timestamp: new Date().toISOString() });
-  });
+  endpoint.onProof(async (message) => { log({ event: 'proof_received', from: message.from, payload: message.payload, timestamp: new Date().toISOString() }); });
 
   await endpoint.start();
+
+  // Auto-register to Registry with candidates
+  if (capTypes.length > 0 && networkConfig.candidates.length > 0) {
+    try {
+      const regClient = new RegistryClient({ registryUrl: REGISTRY_URL });
+      // Pick best non-relay candidate as primary endpoint for backward compat
+      const bestDirect = networkConfig.candidates.find(c => c.type !== 'relay') || networkConfig.candidates[0];
+      await regClient.register({ name: id.agent_id, capabilities: caps, endpoint: bestDirect.url, candidates: networkConfig.candidates }, id);
+      log({ event: 'auto_registered', registry: REGISTRY_URL, candidates: networkConfig.candidates.length });
+    } catch (e) { log({ event: 'auto_register_failed', error: e.message }); }
+  }
+
   console.log(JSON.stringify({
-    status: 'listening',
-    agent_id: id.agent_id,
-    did: id.did,
-    endpoint: endpoint.getEndpointUrl(),
-    port: p,
-    capabilities: capTypes,
+    status: 'listening', agent_id: id.agent_id, did: id.did,
+    port: p, candidates: networkConfig.candidates, capabilities: capTypes,
     policy: { rateLimit: policy.rateLimit, maxPayloadBytes: policy.maxPayloadBytes, maxConcurrent: policy.maxConcurrent, allowedDIDs: policy.allowedDIDs.length, blockedDIDs: policy.blockedDIDs.length },
-    executor: EXECUTOR_URL || 'not configured (echo mode)',
-    inbox: INBOX_FILE,
+    executor: EXECUTOR_URL || 'echo mode', inbox: INBOX_FILE,
   }, null, 2));
 
   process.on('SIGINT', async () => { await endpoint.stop(); process.exit(0); });
@@ -426,10 +262,7 @@ async function cmdStart(port) {
 
 async function cmdInbox(count) {
   const n = parseInt(count || '20');
-  if (!existsSync(INBOX_FILE)) {
-    console.log(JSON.stringify({ messages: [], count: 0 }));
-    return;
-  }
+  if (!existsSync(INBOX_FILE)) { console.log(JSON.stringify({ messages: [], count: 0 })); return; }
   const lines = readFileSync(INBOX_FILE, 'utf-8').trim().split('\n').filter(Boolean);
   const messages = lines.slice(-n).map(l => JSON.parse(l));
   console.log(JSON.stringify({ messages, count: messages.length, total: lines.length }, null, 2));
@@ -437,15 +270,14 @@ async function cmdInbox(count) {
 
 async function cmdRegister(name, capabilities, endpointUrl) {
   const id = requireIdentity();
-  const client = new RegistryClient({ registryUrl: REGISTRY_URL });
   const caps = (capabilities || 'general').split(',').map(c => ({ type: c.trim(), description: c.trim() }));
   saveCapabilities(caps);
-  const entry = await client.register({
-    name: name || id.agent_id,
-    capabilities: caps,
-    endpoint: endpointUrl || 'http://localhost:3100',
-  }, id);
-  console.log(JSON.stringify({ status: 'registered', did: entry.did, name: entry.name, capabilities: caps.map(c => c.type), registry: REGISTRY_URL }, null, 2));
+  // If no endpoint provided, use saved network config
+  let ep = endpointUrl;
+  if (!ep) { const net = loadNetwork(); ep = net?.endpoint || 'http://localhost:3100'; }
+  const client = new RegistryClient({ registryUrl: REGISTRY_URL });
+  const entry = await client.register({ name: name || id.agent_id, capabilities: caps, endpoint: ep }, id);
+  console.log(JSON.stringify({ status: 'registered', did: entry.did, name: entry.name, capabilities: caps.map(c => c.type), endpoint: ep, registry: REGISTRY_URL }, null, 2));
 }
 
 async function cmdSearch(capability) {
@@ -459,66 +291,87 @@ async function cmdHandshake(remoteEndpoint, remoteDid) {
   const client = new AgentClient(id);
   const hsManager = new HandshakeManager(id);
   let did = remoteDid;
-  if (!did) {
-    const health = await client.health(remoteEndpoint);
-    did = health.did;
-  }
+  if (!did) { const h = await client.health(remoteEndpoint); did = h.did; }
   const session = await client.handshake(remoteEndpoint, hsManager, did);
   console.log(JSON.stringify({ status: 'handshake_complete', sessionId: session.sessionId, remoteDid: did, encrypted: session.encrypted }, null, 2));
-  const sessFile = resolve(ATEL_DIR, 'sessions.json');
-  let sessions = {};
-  if (existsSync(sessFile)) sessions = JSON.parse(readFileSync(sessFile, 'utf-8'));
+  const sf = resolve(ATEL_DIR, 'sessions.json');
+  let sessions = {}; if (existsSync(sf)) sessions = JSON.parse(readFileSync(sf, 'utf-8'));
   sessions[remoteEndpoint] = { did, sessionId: session.sessionId, encrypted: session.encrypted };
-  writeFileSync(sessFile, JSON.stringify(sessions, null, 2));
+  writeFileSync(sf, JSON.stringify(sessions, null, 2));
 }
 
-async function cmdTask(remoteEndpoint, taskJson) {
+async function cmdTask(target, taskJson) {
   const id = requireIdentity();
   const client = new AgentClient(id);
   const hsManager = new HandshakeManager(id);
-  const sessFile = resolve(ATEL_DIR, 'sessions.json');
+
+  let remoteEndpoint = target;
   let remoteDid;
-  if (existsSync(sessFile)) {
-    const sessions = JSON.parse(readFileSync(sessFile, 'utf-8'));
-    if (sessions[remoteEndpoint]) remoteDid = sessions[remoteEndpoint].did;
+
+  // If target looks like a DID or name, search Registry and try candidates
+  if (!target.startsWith('http')) {
+    const regClient = new RegistryClient({ registryUrl: REGISTRY_URL });
+    let entry;
+    // Try as DID first
+    try {
+      const resp = await fetch(`${REGISTRY_URL}/registry/v1/agent/${encodeURIComponent(target)}`);
+      if (resp.ok) entry = await resp.json();
+    } catch {}
+    // Try as capability search
+    if (!entry) {
+      const results = await regClient.search({ type: target, limit: 5 });
+      if (results.length > 0) entry = results[0];
+    }
+    if (!entry) { console.error(`Agent not found: ${target}`); process.exit(1); }
+
+    remoteDid = entry.did;
+
+    // Try candidates if available
+    if (entry.candidates && entry.candidates.length > 0) {
+      console.log(JSON.stringify({ event: 'connecting', did: remoteDid, candidates: entry.candidates.length }));
+      const conn = await connectToAgent(entry.candidates);
+      if (conn) {
+        remoteEndpoint = conn.url;
+        console.log(JSON.stringify({ event: 'connected', type: conn.candidateType, url: conn.url, latencyMs: conn.latencyMs }));
+      } else {
+        console.error('All candidates unreachable'); process.exit(1);
+      }
+    } else {
+      remoteEndpoint = entry.endpoint;
+    }
   }
+
+  // Handshake
+  const sf = resolve(ATEL_DIR, 'sessions.json');
   if (!remoteDid) {
-    const health = await client.health(remoteEndpoint);
-    remoteDid = health.did;
-    const session = await client.handshake(remoteEndpoint, hsManager, remoteDid);
-    let sessions = {};
-    if (existsSync(sessFile)) sessions = JSON.parse(readFileSync(sessFile, 'utf-8'));
-    sessions[remoteEndpoint] = { did: remoteDid, sessionId: session.sessionId, encrypted: session.encrypted };
-    writeFileSync(sessFile, JSON.stringify(sessions, null, 2));
-  } else {
-    await client.handshake(remoteEndpoint, hsManager, remoteDid);
+    const h = await client.health(remoteEndpoint); remoteDid = h.did;
   }
+  await client.handshake(remoteEndpoint, hsManager, remoteDid);
+  let sessions = {}; if (existsSync(sf)) sessions = JSON.parse(readFileSync(sf, 'utf-8'));
+  sessions[remoteEndpoint] = { did: remoteDid };
+  writeFileSync(sf, JSON.stringify(sessions, null, 2));
+
+  // Send task
   const payload = typeof taskJson === 'string' ? JSON.parse(taskJson) : taskJson;
   const msg = createMessage({ type: 'task', from: id.did, to: remoteDid, payload, secretKey: id.secretKey });
   const result = await client.sendTask(remoteEndpoint, msg, hsManager);
-  console.log(JSON.stringify({ status: 'task_sent', remoteDid, result }, null, 2));
+  console.log(JSON.stringify({ status: 'task_sent', remoteDid, via: remoteEndpoint, result }, null, 2));
 }
 
 async function cmdResult(taskId, resultJson) {
-  // Submit execution result back to local atel endpoint
   const result = typeof resultJson === 'string' ? JSON.parse(resultJson) : resultJson;
-  const localUrl = `http://localhost:${process.env.ATEL_PORT || '3100'}/atel/v1/result`;
-  const resp = await fetch(localUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ taskId, result, success: true }),
-  });
-  const data = await resp.json();
-  console.log(JSON.stringify(data, null, 2));
+  const resp = await fetch(`http://localhost:${process.env.ATEL_PORT || '3100'}/atel/v1/result`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ taskId, result, success: true }) });
+  console.log(JSON.stringify(await resp.json(), null, 2));
 }
 
 // ─── Main ────────────────────────────────────────────────────────
 
 const [,, cmd, ...args] = process.argv;
-
 const commands = {
   init: () => cmdInit(args[0]),
   info: () => cmdInfo(),
+  setup: () => cmdSetup(args[0]),
+  verify: () => cmdVerify(),
   start: () => cmdStart(args[0]),
   inbox: () => cmdInbox(args[0]),
   register: () => cmdRegister(args[0], args[1], args[2]),
@@ -534,9 +387,11 @@ if (!cmd || !commands[cmd]) {
 Usage: atel <command> [args]
 
 Commands:
-  init [name]                          Create agent identity + default policy
-  info                                 Show identity, capabilities, policy
-  start [port]                         Start endpoint (default: 3100)
+  init [name]                          Create agent identity + security policy
+  info                                 Show identity, capabilities, network, policy
+  setup [port]                         Configure network (detect IP, UPnP, verify)
+  verify                               Verify port reachability
+  start [port]                         Start endpoint (auto network + auto register)
   inbox [count]                        Show received messages (default: 20)
   register [name] [caps] [endpoint]    Register on public registry
   search <capability>                  Search registry for agents
@@ -545,22 +400,16 @@ Commands:
   result <taskId> <json>               Submit execution result (from executor)
 
 Environment:
-  ATEL_DIR            Identity directory (default: .atel)
-  ATEL_REGISTRY       Registry URL (default: http://47.251.8.19:8100)
-  ATEL_EXECUTOR_URL   Local executor HTTP endpoint (for async task forwarding)
-  ATEL_SOLANA_PRIVATE_KEY   Solana private key for on-chain anchoring
-  ATEL_SOLANA_RPC_URL       Solana RPC URL (default: mainnet-beta)
-
-Security Policy (.atel/policy.json):
-  rateLimit           Max tasks per minute (default: 60)
-  maxPayloadBytes     Max payload size (default: 1MB)
-  maxConcurrent       Max concurrent tasks (default: 10)
-  allowedDIDs         DID whitelist (empty = allow all)
-  blockedDIDs         DID blacklist`);
+  ATEL_DIR                Identity directory (default: .atel)
+  ATEL_REGISTRY           Registry URL (default: http://47.251.8.19:8100)
+  ATEL_EXECUTOR_URL       Local executor HTTP endpoint
+  ATEL_SOLANA_PRIVATE_KEY Solana key for on-chain anchoring
+  ATEL_SOLANA_RPC_URL     Solana RPC (default: mainnet-beta)
+
+Network: atel start auto-detects public IP, attempts UPnP port mapping,
+and registers to the Registry. If UPnP fails, configure port forwarding
+on your router and run: atel verify`);
   process.exit(cmd ? 1 : 0);
 }
 
-commands[cmd]().catch(err => {
-  console.error(JSON.stringify({ error: err.message }));
-  process.exit(1);
-});
+commands[cmd]().catch(err => { console.error(JSON.stringify({ error: err.message })); process.exit(1); });