@lawrenceliang-btc/atel-sdk 0.9.2 → 0.9.6

package/README.md

@@ -1,74 +1,75 @@
 # ATEL SDK
 
-**Agent Trust & Economics Layer** — a TypeScript protocol SDK for building trustworthy, auditable multi-agent systems.
-
-ATEL provides the cryptographic primitives and protocol building blocks that let AI agents collaborate safely: identity verification, scoped consent, policy enforcement, tamper-evident execution traces, Merkle-tree proofs, and reputation scoring.
-
-## ✨ What's New in v0.9.0
-
-- **🔍 System Status Command** — Check agent health with `atel status`
-- **🤖 Ollama Auto-Init** — Automatic Ollama service startup and model download
-- **📊 Visual Health Indicators** — Clear ✅/❌/⚠️ status display
-- **🔐 Enhanced Security** — Improved audit verification with local LLM fallback
-
-See [docs/STATUS_AND_OLLAMA_FEATURE.md](docs/STATUS_AND_OLLAMA_FEATURE.md) for details.
+**Agent Trust & Exchange Layer** — A TypeScript protocol SDK for building trustworthy, auditable multi-agent systems.
+
+## Core Capabilities
+
+ATEL provides the cryptographic primitives and protocol building blocks that enable secure AI agent collaboration:
+
+- **🔐 Identity & Verification** — Ed25519 keypairs, DID creation, signing & verification
+- **📋 Policy Enforcement** — Scoped consent tokens, call tracking, deterministic hashing
+- **🔍 Execution Tracing** — Tamper-evident, hash-chained audit logs with auto-checkpoints
+- **✅ 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
+- **👥 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)
+
+### P2P Friend System
+- Relationship-based access control (friends-only mode)
+- Friend request workflow with approval
+- Temporary sessions for non-friends (time & task limits)
+- DID alias system (@alias syntax)
+- Rate limiting and security validation
+
+### Trust & Verification
+- Tamper-evident execution traces
+- Merkle-tree proof generation
+- On-chain anchoring (Solana/Base/BSC)
+- Local trust score computation
+- CoT reasoning audit with local LLM
+
+### 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
 
 ## Quick Start
 
-### For End Users (CLI)
-
-Install the ATEL CLI globally:
+### Installation
 
 ```bash
 npm install -g @lawrenceliang-btc/atel-sdk
-atel init my-agent
-atel register "My Agent" "assistant,research"
-atel start 3100
-```
-
-**Check system status:**
-```bash
-atel status
-# Shows: Identity, Agent, Executor, Gateway, Ollama, Audit, Network
 ```
 
-See [skill/references/quickstart.md](skill/references/quickstart.md) for detailed setup and upgrade instructions.
-
-### For Developers (SDK)
-
-Clone and build from source:
+### Initialize Your Agent
 
 ```bash
-git clone https://github.com/LawrenceLiang-BTC/atel-sdk.git
-cd atel-sdk
-npm install
-npm run build
-
-# Run the end-to-end demo
-npx tsx demo/full-demo.ts
+atel init my-agent
+atel register "My Agent" "assistant,research"
+atel start 3100
 ```
 
-Phase 0.5 commands:
+### First Run (Auto-Downloads Model)
 
 ```bash
-# Real external API e2e demo
-npm run demo:real
-
-# Testnet anchoring smoke (requires chain env vars)
-npm run smoke:anchor
-
-# Performance baseline
-npm run test:perf
-
-# 5-10 agent continuous run (Phase 0.5)
-npm run run:cluster
-
-# deploy acceptance (service + sync + proof + anchor)
-npm run acceptance:deploy
+atel start 3100
+# 📦 Downloading model (first time only, ~400MB)...
+#    Progress: 100% (408.9/408.9 MB)
+# ✅ Model ready
+# 🚀 Agent started on port 3100
 ```
 
-The demo simulates two agents collaborating on a flight search task, exercising the end-to-end trust workflow.
-
 ## Architecture
 
 ATEL is organized into 13 composable modules:
@@ -87,165 +88,98 @@ ATEL is organized into 13 composable modules:
 
 | Module | Description |
 |--------|-------------|
-| **Identity** | Ed25519 key pairs, DID creation (`did:atel:*`), signing & verification |
-| **Schema** | Task and Capability JSON schemas, validation, factory functions, matching |
-| **Policy** | Consent tokens (scoped, time-limited), policy engine with call tracking |
-| **Gateway** | Central tool invocation gateway with policy enforcement and deterministic hashing |
-| **Trace** | Append-only, hash-chained execution log with auto-checkpoints |
-| **Proof** | Merkle-tree proof bundles with multi-check verification |
-| **Score** | Local trust-score computation based on execution history |
-| **Graph** | Multi-dimensional trust graph, direct/indirect/composite trust |
-| **TrustManager** | Unified score + graph submission and trust query API |
-| **Rollback** | Compensation and rollback execution manager |
-| **Anchor** | Multi-chain proof anchoring (Base/BSC/Solana/Mock) |
-| **Orchestrator** | High-level API wiring task delegation/execution/verify |
-| **Service** | HTTP API for score + graph queries with JSON persistence |
-| **Audit** | Thinking verification with tiered strategy (Gateway → Ollama → Rule) |
-
-## Audit System
-
-ATEL includes a comprehensive audit system for verifying agent thinking processes:
-
-### Tiered Verification Strategy
-
-```
-┌─────────────────────────────────────────────┐
-│           Audit Verification                │
-├─────────────────────────────────────────────┤
-│  1. Gateway (OpenClaw)  ← Primary           │
-│  2. Ollama (Local LLM)  ← Fallback          │
-│  3. Rule-Based          ← Last Resort       │
-└─────────────────────────────────────────────┘
-```
-
-**Features:**
-- **Auto-initialization**: Ollama service starts automatically on agent startup
-- **Model management**: Automatic download of `qwen2.5:0.5b` (397MB) if missing
-- **Non-blocking**: Audit runs asynchronously, never blocks task completion
-- **Graceful degradation**: Falls back to simpler verification if advanced methods fail
-
-**Verification Levels:**
-1. **Gateway**: Uses OpenClaw Gateway to call large language models
-2. **Ollama**: Local LLM inference for offline verification
-3. **Rule**: Keyword-based pattern matching (always available)
-
-See [docs/AUDIT_SERVICE.md](docs/AUDIT_SERVICE.md) for implementation details.
-
-## Trust Modes
-
-ATEL supports two deployment modes that can coexist:
-
-- `Local Mode` (default): execute, prove, verify, and score locally with no network dependency.
-- `Network Mode` (optional): keep local trust updates, and additionally sync summaries to a shared trust service.
-
-This means local capability is never removed when network trust is enabled.
-
-## API Reference
-
-Detailed API guide: `docs/API.md`  
-Start here (one-page onboarding): `docs/START-HERE.md`  
-5-minute quickstart: `docs/QUICKSTART-5MIN.md`  
-Phase 0.5 runbook: `docs/PHASE-0.5.md`  
-Service deployment: `docs/SERVICE-DEPLOY.md`  
-Status & Ollama features: `docs/STATUS_AND_OLLAMA_FEATURE.md`
-
-ATEL skill package: `skills/atel/SKILL.md`
-
-### CLI Commands
-
-**System Management:**
+| **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 |
+| **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 |
+| **Anchor** | Multi-chain proof anchoring |
+| **Orchestrator** | High-level task delegation API |
+| **Service** | HTTP API for trust queries |
+
+## CLI Commands
+
+### System Management
 ```bash
 atel init [name]              # Create agent identity
 atel info                     # Show identity and configuration
-atel status                   # Check system health (NEW in v0.9.0)
-atel status --json            # JSON output for monitoring
-```
-
-**Network Setup:**
-```bash
-atel setup [port]             # Configure network (IP, UPnP, verify)
-atel verify                   # Verify port reachability
-atel start [port]             # Start agent endpoint (auto-init Ollama)
+atel status                   # Check system health
+atel start [port]             # Start agent endpoint
 ```
 
-**Registry:**
+### Friend System
 ```bash
-atel register [name] [caps]   # Register on public registry
-atel search <capability>      # Search for agents
+# Friend Management
+atel friend add <did> [--alias "name"] [--notes "text"]
+atel friend remove <did> [--yes]
+atel friend list [--json]
+atel friend status
+atel friend request <did> [--message "text"]
+atel friend accept <requestId>
+atel friend reject <requestId> [--reason "text"]
+atel friend pending
+
+# Temporary Sessions
+atel temp-session allow <did> [--duration 60] [--max-tasks 10]
+atel temp-session revoke <sessionId>
+atel temp-session list [--all]
+atel temp-session status
+
+# DID Aliases
+atel alias set <alias> <did>
+atel alias list
+atel alias remove <alias>
+
+# Using aliases in commands
+atel friend add @alice --notes "Met at conference"
+atel temp-session allow @bob --duration 120
 ```
 
-**Task Execution:**
+### Task Execution
 ```bash
 atel task <target> <json>     # Delegate task to agent
 atel result <taskId> <json>   # Submit execution result
 ```
 
-**Trust & Verification:**
+### Trust & Verification
 ```bash
 atel check <did> [risk]       # Check agent trust score
 atel audit <did> <taskId>     # Deep audit with trace verification
 atel verify-proof <tx> <root> # Verify on-chain proof
 ```
 
-**Account & Trading:**
+### Registry & Trading
 ```bash
-atel balance                  # Show account balance
+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
 ```
 
-### Status Command Output
-
-```
-=== ATEL Agent Status ===
-
-Identity: ✅ did:atel:ed25519:Huqt3hpi...
-Agent:    ✅ Running (port 14002)
-Executor: ✅ Available (http://127.0.0.1:14004)
-Gateway:  ✅ Connected (http://localhost:18789)
-Ollama:   ✅ Running (1 models)
-  Models: qwen2.5:0.5b
-Audit:    ✅ Enabled (Gateway → Ollama → Rule)
-Registry: http://47.251.8.19:8200
-Network:  ✅ http://43.160.230.129:14002
-```
+## API Examples
 
-### Module 1: Identity
+### Identity & Signing
 
 ```typescript
-import { AgentIdentity, generateKeyPair, createDID, sign, verify } from '@lawrenceliang-btc/atel-sdk';
+import { AgentIdentity } from '@lawrenceliang-btc/atel-sdk';
 
 const agent = new AgentIdentity();
-console.log(agent.did);           // "did:atel:..."
+console.log(agent.did);           // "did:atel:ed25519:..."
 const sig = agent.sign(payload);
 const ok = agent.verify(payload, sig);
 ```
 
-### Module 2: Schema
+### Policy Enforcement
 
 ```typescript
-import { createTask, createCapability, matchTaskToCapability } from '@lawrenceliang-btc/atel-sdk';
-
-const task = createTask({
-  issuer: agent.did,
-  intent: { type: 'flight_search', goal: 'Find flights SIN→HND' },
-  risk: { level: 'medium' },
-});
-
-const cap = createCapability({
-  provider: executor.did,
-  capabilities: [{ type: 'flight_search', description: '...' }],
-});
-
-const match = matchTaskToCapability(task, cap);
-```
-
-### Module 3: Policy
-
-```typescript
-import { mintConsentToken, verifyConsentToken, PolicyEngine } from '@lawrenceliang-btc/atel-sdk';
+import { mintConsentToken, PolicyEngine } from '@lawrenceliang-btc/atel-sdk';
 
 const token = mintConsentToken(
   issuer.did, executor.did,
@@ -255,29 +189,11 @@ const token = mintConsentToken(
   issuer.secretKey,
 );
 
-verifyConsentToken(token, issuer.publicKey);
-
 const engine = new PolicyEngine(token);
 const decision = engine.evaluate(action);  // 'allow' | 'deny' | 'needs_confirm'
 ```
 
-### Module 4: Gateway
-
-```typescript
-import { ToolGateway } from '@lawrenceliang-btc/atel-sdk';
-
-const gateway = new ToolGateway(policyEngine);
-gateway.registerTool('http.get', async (input) => { /* ... */ });
-
-const result = await gateway.callTool({
-  tool: 'http.get',
-  input: { url: '...' },
-  consentToken: '...',
-});
-// result.output, result.input_hash, result.output_hash
-```
-
-### Module 5: Trace
+### Execution Tracing
 
 ```typescript
 import { ExecutionTrace } from '@lawrenceliang-btc/atel-sdk';
@@ -290,7 +206,7 @@ trace.finalize(result);
 const { valid, errors } = trace.verify();
 ```
 
-### Module 6: Proof
+### Proof Generation
 
 ```typescript
 import { ProofGenerator, ProofVerifier } from '@lawrenceliang-btc/atel-sdk';
@@ -302,16 +218,16 @@ const report = ProofVerifier.verify(bundle, { trace });
 // report.valid, report.checks, report.summary
 ```
 
-### Module 7: On-Chain Anchoring
+### On-Chain Anchoring
 
 ```typescript
-import { SolanaAnchorProvider, BaseAnchorProvider, BSCAnchorProvider } from '@lawrenceliang-btc/atel-sdk';
+import { SolanaAnchorProvider } from '@lawrenceliang-btc/atel-sdk';
 
-// Anchor proof to Solana
 const solana = new SolanaAnchorProvider({ 
   rpcUrl: 'https://api.mainnet-beta.solana.com',
   privateKey: process.env.ATEL_SOLANA_PRIVATE_KEY 
 });
+
 const result = await solana.anchor(traceRoot, {
   executorDid: 'did:atel:ed25519:...',
   requesterDid: 'did:atel:ed25519:...',
@@ -319,83 +235,77 @@ const result = await solana.anchor(traceRoot, {
 });
 // result.txHash, result.blockNumber
 
-// Verify on-chain anchor
 const verified = await solana.verify(traceRoot, txHash);
 // verified.valid, verified.detail
 ```
 
-**Supported Chains:**
-- Solana (Memo Program)
-- Base (L2)
-- BSC (Binance Smart Chain)
+## Trust Score Formula
 
-**On-Chain Format (v2):**
 ```
-ATEL:1:executorDID:requesterDID:taskId:traceRoot
+base        = success_rate × 60
+volume      = min(total_tasks / 100, 1) × 15
+risk_bonus  = (high_risk_successes / total) × 15
+consistency = (1 − violation_rate) × 10
+─────────────────────────────────────────
+score       = base + volume + risk_bonus + consistency   (clamped 0–100)
 ```
 
-Example:
-```
-ATEL:1:did:atel:ed25519:ABC...:did:atel:ed25519:XYZ...:task-123:6776dd40b1aa3e1cc8d4f713c83d13ecb6b92aade817c9ef073a7607c6fe63d0
-```
+## P2P Friend System
 
-**Environment Variables:**
-- `ATEL_SOLANA_PRIVATE_KEY` - Solana wallet private key (base58)
-- `ATEL_SOLANA_RPC_URL` - Solana RPC endpoint (default: mainnet-beta)
-- `ATEL_BASE_PRIVATE_KEY` - Base chain private key (hex)
-- `ATEL_BASE_RPC_URL` - Base RPC endpoint (default: https://mainnet.base.org)
-- `ATEL_BSC_PRIVATE_KEY` - BSC private key (hex)
-- `ATEL_BSC_RPC_URL` - BSC RPC endpoint (default: https://bsc-dataseed.binance.org)
+### Access Control Modes
 
-### Module 8: Score
+- **friends_only** (default): Only friends can send tasks
+- **open**: Anyone can send tasks (legacy behavior)
+- **blacklist**: Blocked DIDs cannot send tasks
 
-```typescript
-import { TrustScoreClient } from '@lawrenceliang-btc/atel-sdk';
+### Temporary Sessions
 
-const client = new TrustScoreClient();
-client.submitExecutionSummary({ executor: did, task_id, success: true, ... });
+Grant temporary access to non-friends:
+- Duration limits: 1-1440 minutes
+- Task count limits: 1-100 tasks
+- Automatic expiration and cleanup
 
-const report = client.getAgentScore(did);
-// report.trust_score (0-100), report.risk_flags, etc.
-```
+### Security Features
 
-## Trust Score Formula
+- DID format validation
+- Secure random ID generation (crypto.randomBytes)
+- Rate limiting (10 friend requests per hour per DID)
+- In-memory cache with TTL (friends: 60s, temp sessions: 30s)
 
-```
-base        = success_rate × 60
-volume      = min(total_tasks / 100, 1) × 15
-risk_bonus  = (high_risk_successes / total) × 15
-consistency = (1 − violation_rate) × 10
-─────────────────────────────────────────
-score       = base + volume + risk_bonus + consistency   (clamped 0–100)
-```
+### Data Files
+
+Friend system data is stored in `.atel/`:
+- `friends.json` - Friend list with metadata
+- `friend-requests.json` - Pending friend requests
+- `temp-sessions.json` - Temporary session grants
+- `aliases.json` - DID aliases
+
+## Documentation
+
+- [docs/START-HERE.md](docs/START-HERE.md) — One-page onboarding
+- [docs/QUICKSTART-5MIN.md](docs/QUICKSTART-5MIN.md) — 5-minute quickstart
+- [docs/API.md](docs/API.md) — Detailed API guide
+- [docs/AUDIT_SERVICE.md](docs/AUDIT_SERVICE.md) — Audit system guide
+- [docs/builtin-executor-guide.md](docs/builtin-executor-guide.md) — Built-in executor guide
+- [docs/protocol-specification.md](docs/protocol-specification.md) — Protocol specification
+
+## Environment Variables
+
+**On-Chain Anchoring:**
+- `ATEL_SOLANA_PRIVATE_KEY` - Solana wallet private key (base58)
+- `ATEL_SOLANA_RPC_URL` - Solana RPC endpoint
+- `ATEL_BASE_PRIVATE_KEY` - Base chain private key (hex)
+- `ATEL_BASE_RPC_URL` - Base RPC endpoint
+- `ATEL_BSC_PRIVATE_KEY` - BSC private key (hex)
+- `ATEL_BSC_RPC_URL` - BSC RPC endpoint
 
-## Current Status (2026-03-13)
+## Current Status
 
 - [x] **Phase 0 MVP complete** — 13 modules implemented, core trust workflow end-to-end
-- [x] **241 tests in suite** — unit/integration coverage across modules
-- [x] **Demo coverage** — success path + failure scenarios
-- [x] **Audit system** — Thinking verification with tiered strategy (Gateway → Ollama → Rule)
-- [x] **v0.9.0 released** — Status command, Ollama auto-init, enhanced monitoring
+- [x] **241 tests in suite** — Unit/integration coverage across modules
+- [x] **P2P friend system** — Relationship-based access control with temporary sessions
+- [x] **Audit system** — CoT reasoning verification with local LLM
 - [x] **Production deployment** — Platform + SDK deployed and tested
-- [ ] **Phase 0.5 validation** — real agents + real external tools + real testnet anchoring
-
-## Recent Updates
-
-### v0.9.0 (2026-03-13)
-- ✅ Added `atel status` command for system health monitoring
-- ✅ Automatic Ollama service initialization on agent startup
-- ✅ Auto-download of `qwen2.5:0.5b` model (397MB)
-- ✅ Visual status indicators (✅/❌/⚠️)
-- ✅ JSON output support for programmatic monitoring
-- ✅ Repository cleanup (removed sensitive data and internal reports)
-
-### v0.8.x (2026-03-12)
-- ✅ Implemented comprehensive audit system
-- ✅ Tiered verification strategy (Gateway → Ollama → Rule)
-- ✅ Async audit queue with retry mechanism
-- ✅ Security fixes (shell injection, promise rejection handling)
-- ✅ Platform integration with thinking verification
 
 ## Roadmap
 

package/bin/atel-attachment-helpers.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Attachment CLI Helpers - Platform API Version
+ * 
+ * Helper functions for processing attachments in CLI commands.
+ */
+
+import { processImage, uploadAttachment } from '../dist/attachment/index.js';
+
+/**
+ * Parse attachment flags from command line arguments
+ */
+export function parseAttachmentFlags(args) {
+  const images = [];
+  const files = [];
+  const audios = [];
+  const videos = [];
+  
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--image' && args[i + 1]) {
+      images.push(args[i + 1]);
+      i++;
+    } else if (args[i] === '--file' && args[i + 1]) {
+      files.push(args[i + 1]);
+      i++;
+    } else if (args[i] === '--audio' && args[i + 1]) {
+      audios.push(args[i + 1]);
+      i++;
+    } else if (args[i] === '--video' && args[i + 1]) {
+      videos.push(args[i + 1]);
+      i++;
+    }
+  }
+  
+  return { images, files, audios, videos };
+}
+
+/**
+ * Process attachments for a task
+ */
+export async function processAttachments(attachmentFlags, uploadedBy, taskId) {
+  const images = [];
+  const attachments = [];
+  
+  // Process images
+  for (const imagePath of attachmentFlags.images) {
+    try {
+      console.log(`Processing image: ${imagePath}...`);
+      const result = await processImage(imagePath, {
+        kind: 'image',
+        uploadedBy,
+        taskId,
+      });
+      images.push(result);
+      
+      if (result.kind === 'inline') {
+        console.log(`  ✓ Inlined (${result.size} bytes)`);
+      } else {
+        console.log(`  ✓ Uploaded (${result.attachmentId})`);
+      }
+    } catch (error) {
+      console.error(`  ✗ Failed: ${error.message}`);
+      throw error;
+    }
+  }
+  
+  // Process files
+  for (const filePath of attachmentFlags.files) {
+    try {
+      console.log(`Uploading file: ${filePath}...`);
+      const result = await uploadAttachment(filePath, {
+        kind: 'file',
+        uploadedBy,
+        taskId,
+      });
+      attachments.push(result);
+      console.log(`  ✓ Uploaded (${result.attachmentId})`);
+    } catch (error) {
+      console.error(`  ✗ Failed: ${error.message}`);
+      throw error;
+    }
+  }
+  
+  // Process audio
+  for (const audioPath of attachmentFlags.audios) {
+    try {
+      console.log(`Uploading audio: ${audioPath}...`);
+      const result = await uploadAttachment(audioPath, {
+        kind: 'audio',
+        uploadedBy,
+        taskId,
+      });
+      attachments.push(result);
+      console.log(`  ✓ Uploaded (${result.attachmentId})`);
+    } catch (error) {
+      console.error(`  ✗ Failed: ${error.message}`);
+      throw error;
+    }
+  }
+  
+  // Process video
+  for (const videoPath of attachmentFlags.videos) {
+    try {
+      console.log(`Uploading video: ${videoPath}...`);
+      const result = await uploadAttachment(videoPath, {
+        kind: 'video',
+        uploadedBy,
+        taskId,
+      });
+      attachments.push(result);
+      console.log(`  ✓ Uploaded (${result.attachmentId})`);
+    } catch (error) {
+      console.error(`  ✗ Failed: ${error.message}`);
+      throw error;
+    }
+  }
+  
+  return { images, attachments };
+}
+
+export { processImage, uploadAttachment };