agentvault 1.0.0

package/src/archival/arweave-client.ts

@@ -0,0 +1,289 @@
+/**
+ * Arweave Client
+ *
+ * Handles interaction with Arweave network for permanent data archival.
+ * Supports uploading data, retrieving transactions, and checking status.
+ */
+
+export interface ArweaveConfig {
+  host?: string;
+  port?: number;
+  protocol?: 'http' | 'https';
+  timeout?: number;
+  logging?: boolean;
+}
+
+export interface UploadOptions {
+  tags?: Record<string, string>;
+  fee?: number;
+}
+
+export interface ArchiveTransaction {
+  id: string;
+  owner: string;
+  tags: Record<string, string>;
+  size: number;
+  timestamp: Date;
+  block?: {
+    height: number;
+    indep_hash: string;
+  };
+}
+
+export interface UploadResult {
+  success: boolean;
+  transactionId?: string;
+  error?: string;
+}
+
+export type JWKInterface = Record<string, any>;
+
+export class ArweaveClient {
+  private config: Required<ArweaveConfig>;
+  private client: any = null;
+
+  constructor(config: ArweaveConfig = {}) {
+    this.config = {
+      host: config.host || 'arweave.net',
+      port: config.port || 443,
+      protocol: config.protocol || 'https',
+      timeout: config.timeout || 20000,
+      logging: config.logging || false,
+    };
+  }
+
+  /**
+   * Initialize Arweave client (lazy loading)
+   */
+  private async getClient(): Promise<any> {
+    if (!this.client) {
+      try {
+        const Arweave = await this.importArweave();
+        this.client = new Arweave({
+          host: this.config.host,
+          port: this.config.port,
+          protocol: this.config.protocol,
+          timeout: this.config.timeout,
+          logging: this.config.logging,
+        });
+      } catch (_error) {
+        throw new Error(
+          'arweave is required for ArweaveClient. Install with: npm install arweave',
+        );
+      }
+    }
+    return this.client;
+  }
+
+  /**
+   * Dynamically import arweave (optional dependency)
+   */
+  private async importArweave(): Promise<any> {
+    try {
+      const dynamicImport = new Function('modulePath', 'return import(modulePath)') as (
+        modulePath: string
+      ) => Promise<{ default: any }>;
+      const arweaveModule = await dynamicImport('arweave');
+      return arweaveModule.default;
+    } catch (_error) {
+      throw new Error(
+        'arweave is required for ArweaveClient. Install with: npm install arweave',
+      );
+    }
+  }
+
+  /**
+   * Upload data to Arweave
+   */
+  async uploadData(
+    data: string | Buffer,
+    jwk: JWKInterface,
+    options: UploadOptions = {},
+  ): Promise<UploadResult> {
+    try {
+      const client = await this.getClient();
+      const transaction = await client.createTransaction(
+        {
+          data: typeof data === 'string' ? data : data.toString('base64'),
+        },
+        jwk,
+      );
+
+      if (options.tags) {
+        for (const [key, value] of Object.entries(options.tags)) {
+          transaction.addTag(key, value);
+        }
+      }
+
+      await client.transactions.sign(transaction, jwk);
+
+      const response = await client.transactions.post(transaction);
+
+      if (response.status === 200 || response.status === 202) {
+        return {
+          success: true,
+          transactionId: transaction.id,
+        };
+      } else {
+        return {
+          success: false,
+          error: `Upload failed with status ${response.status}`,
+        };
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  /**
+   * Upload JSON data to Arweave
+   */
+  async uploadJSON<T>(
+    jsonData: T,
+    jwk: JWKInterface,
+    options: UploadOptions = {},
+  ): Promise<UploadResult> {
+    return this.uploadData(JSON.stringify(jsonData), jwk, {
+      ...options,
+      tags: {
+        'Content-Type': 'application/json',
+        ...(options.tags || {}),
+      },
+    });
+  }
+
+  /**
+   * Get transaction data by ID
+   */
+  async getTransactionData(transactionId: string): Promise<string | null> {
+    try {
+      const client = await this.getClient();
+      const data = await client.transactions.getData(transactionId, {
+        decode: true,
+      });
+      return data.toString();
+    } catch (error) {
+      console.error(`Failed to fetch transaction ${transactionId}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Get transaction status
+   */
+  async getTransactionStatus(
+    transactionId: string,
+  ): Promise<'pending' | 'confirmed' | 'not_found' | 'error'> {
+    try {
+      const client = await this.getClient();
+      const status = await client.transactions.getStatus(transactionId);
+
+      if (!status) {
+        return 'not_found';
+      }
+
+      if (status.confirmed && status.confirmed.number_of_confirmations > 0) {
+        return 'confirmed';
+      }
+
+      return 'pending';
+    } catch (error) {
+      console.error(`Failed to check status for ${transactionId}:`, error);
+      return 'error';
+    }
+  }
+
+  /**
+   * Get transaction info
+   */
+  async getTransaction(transactionId: string): Promise<ArchiveTransaction | null> {
+    try {
+      const client = await this.getClient();
+      const transaction = await client.transactions.get(transactionId);
+
+      const tags: Record<string, string> = {};
+      transaction.get('tags').forEach((tag: any) => {
+        const name = tag.get('name', { decode: true, string: true });
+        const value = tag.get('value', { decode: true, string: true });
+        if (name && value) {
+          tags[name] = value;
+        }
+      });
+
+      const block = transaction.get('block');
+      let blockInfo;
+      if (block) {
+        blockInfo = {
+          height: block.get('height'),
+          indep_hash: block.get('indep_hash'),
+        };
+      }
+
+      return {
+        id: transaction.id,
+        owner: transaction.owner,
+        tags,
+        size: parseInt(transaction.data_size, 10),
+        timestamp: new Date(parseInt(transaction.last_tx, 10) * 1000),
+        block: blockInfo,
+      };
+    } catch (error) {
+      console.error(`Failed to fetch transaction ${transactionId}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Get wallet balance in AR
+   */
+  async getWalletBalance(address: string): Promise<string> {
+    try {
+      const client = await this.getClient();
+      const balance = await client.wallets.getBalance(address);
+      return client.ar.winstonToAr(balance);
+    } catch (error) {
+      console.error(`Failed to fetch balance for ${address}:`, error);
+      return '0';
+    }
+  }
+
+  /**
+   * Estimate upload cost in AR
+   */
+  async estimateUploadCost(dataSizeBytes: number): Promise<string> {
+    try {
+      const client = await this.getClient();
+      const price = await client.transactions.getPrice(dataSizeBytes);
+      return client.ar.winstonToAr(price);
+    } catch (error) {
+      console.error('Failed to estimate cost:', error);
+      return '0';
+    }
+  }
+
+  /**
+   * Generate a new Arweave wallet
+   */
+  async generateWallet(): Promise<JWKInterface> {
+    const client = await this.getClient();
+    return client.wallets.generate();
+  }
+
+  /**
+   * Get wallet address from JWK
+   */
+  async getAddressFromJWK(jwk: JWKInterface): Promise<string> {
+    const client = await this.getClient();
+    return client.wallets.jwkToAddress(jwk);
+  }
+
+  /**
+   * Create Arweave instance
+   */
+  async getClientInstance(): Promise<any> {
+    return this.getClient();
+  }
+}

package/src/archival/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Archival Module
+ *
+ * Exports archival functionality.
+ */
+
+export * from './arweave-client.js';
+export * from './archive-manager.js';

package/src/backup/backup.ts

@@ -0,0 +1,315 @@
+/**
+ * Backup System
+ *
+ * Portable JSON format backup with embedded manifest and checksums
+ * Stores backups in ~/.agentvault/backups/
+ * CLE-101: Enhanced to include real canister state
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import type { AgentConfig } from '../packaging/types.js';
+
+const AGENTVAULT_DIR = path.join(os.homedir(), '.agentvault');
+const BACKUPS_DIR = path.join(AGENTVAULT_DIR, 'backups');
+
+function ensureBackupsDir(): void {
+  if (!fs.existsSync(AGENTVAULT_DIR)) {
+    fs.mkdirSync(AGENTVAULT_DIR, { recursive: true });
+  }
+  if (!fs.existsSync(BACKUPS_DIR)) {
+    fs.mkdirSync(BACKUPS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Canister state captured in backup
+ */
+export interface CanisterState {
+  canisterId: string;
+  status: 'running' | 'stopped' | 'stopping';
+  memorySize?: bigint;
+  cycles?: bigint;
+  moduleHash?: string;
+  fetchedAt: string;
+  tasks?: unknown[];
+  memory?: unknown;
+  context?: unknown;
+}
+
+export interface BackupManifest {
+  version: string;
+  agentName: string;
+  timestamp: Date;
+  created: Date;
+  agentConfig?: AgentConfig;
+  canisterId?: string;
+  canisterState?: CanisterState;
+  checksums: Record<string, string>;
+  size: number;
+  components: string[];
+}
+
+export interface BackupOptions {
+  agentName: string;
+  outputPath?: string;
+  includeConfig?: boolean;
+  canisterId?: string;
+  includeCanisterState?: boolean;
+}
+
+export interface ImportOptions {
+  inputPath: string;
+  targetAgentName?: string;
+  overwrite?: boolean;
+}
+
+export interface BackupResult {
+  success: boolean;
+  path?: string;
+  error?: string;
+  sizeBytes?: number;
+  manifest?: BackupManifest;
+}
+
+export interface ImportResult {
+  success: boolean;
+  agentName?: string;
+  error?: string;
+  components: string[];
+  warnings: string[];
+}
+
+/**
+ * Fetch canister state for backup
+ */
+async function fetchCanisterState(canisterId: string): Promise<CanisterState | null> {
+  try {
+    const { createICPClient } = await import('../deployment/icpClient.js');
+    const client = createICPClient({ network: 'local' });
+
+    const status = await client.getCanisterStatus(canisterId);
+
+    const statusMap: Record<string, 'running' | 'stopped' | 'stopping'> = {
+      running: 'running',
+      stopped: 'stopped',
+      stopping: 'stopping',
+      pending: 'stopped',
+    };
+
+    const state: CanisterState = {
+      canisterId,
+      status: statusMap[status.status] || 'stopped',
+      memorySize: status.memorySize,
+      cycles: status.cycles,
+      fetchedAt: new Date().toISOString(),
+    };
+
+    try {
+      const tasksResult = await client.callAgentMethod(canisterId, 'getTasks', []);
+      if (tasksResult) {
+        state.tasks = tasksResult as unknown[];
+      }
+    } catch {
+      // Tasks not available
+    }
+
+    try {
+      const memoryResult = await client.callAgentMethod(canisterId, 'getMemory', []);
+      if (memoryResult) {
+        state.memory = memoryResult;
+      }
+    } catch {
+      // Memory not available
+    }
+
+    try {
+      const contextResult = await client.callAgentMethod(canisterId, 'getContext', []);
+      if (contextResult) {
+        state.context = contextResult;
+      }
+    } catch {
+      // Context not available
+    }
+
+    return state;
+  } catch (error) {
+    console.warn('Failed to fetch canister state:', error);
+    return null;
+  }
+}
+
+export async function exportBackup(options: BackupOptions): Promise<BackupResult> {
+  try {
+    ensureBackupsDir();
+    
+    const { agentName, outputPath, includeConfig = true, canisterId, includeCanisterState = true } = options;
+    
+    const timestamp = new Date();
+    const created = new Date();
+    const filename = `${agentName}-${timestamp.toISOString().replace(/[:.]/g, '-')}.json`;
+    const filePath = outputPath || path.join(BACKUPS_DIR, filename);
+    
+    const components: string[] = [];
+    if (includeConfig) {
+      components.push('config');
+    }
+    
+    const manifest: BackupManifest = {
+      version: '1.1',
+      agentName,
+      timestamp,
+      created,
+      checksums: {},
+      size: 0,
+      components,
+    };
+    
+    if (includeConfig) {
+      manifest.canisterId = canisterId || agentName;
+    }
+
+    if (includeCanisterState && canisterId) {
+      const canisterState = await fetchCanisterState(canisterId);
+      if (canisterState) {
+        manifest.canisterState = canisterState;
+        manifest.canisterId = canisterId;
+        components.push('canister-state');
+      }
+    }
+    
+    const content = JSON.stringify(manifest, null, 2);
+    const checksum = crypto.createHash('sha256').update(content).digest('hex');
+    manifest.checksums[filename] = checksum;
+    
+    fs.writeFileSync(filePath, JSON.stringify(manifest, null, 2), 'utf8');
+    
+    const stats = fs.statSync(filePath);
+    manifest.size = stats.size;
+    
+    return {
+      success: true,
+      path: filePath,
+      sizeBytes: stats.size,
+      manifest,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+  }
+}
+
+export async function previewBackup(inputPath: string): Promise<BackupManifest | null> {
+  try {
+    if (!fs.existsSync(inputPath)) {
+      return null;
+    }
+    
+    const content = fs.readFileSync(inputPath, 'utf8');
+    const manifest = JSON.parse(content) as BackupManifest;
+    
+    return manifest;
+  } catch (error) {
+    console.error('Failed to preview backup:', error);
+    return null;
+  }
+}
+
+export async function importBackup(options: ImportOptions): Promise<ImportResult> {
+  try {
+    const { inputPath, targetAgentName, overwrite } = options;
+    
+    if (!fs.existsSync(inputPath)) {
+      return {
+        success: false,
+        agentName: undefined,
+        components: [],
+        warnings: [],
+        error: `Backup file not found: ${inputPath}`,
+      };
+    }
+    
+    const manifest = await previewBackup(inputPath);
+    if (!manifest) {
+      return {
+        success: false,
+        agentName: undefined,
+        components: [],
+        warnings: [],
+        error: 'Invalid backup file',
+      };
+    }
+    
+    const targetName = targetAgentName || manifest.agentName;
+    const warnings: string[] = [];
+    
+    if (!overwrite) {
+      warnings.push('Using dry-run mode; no changes will be made');
+    }
+    
+    return {
+      success: true,
+      agentName: targetName,
+      components: manifest.components,
+      warnings,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      agentName: undefined,
+      components: [],
+      warnings: [],
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+  }
+}
+
+export async function listBackups(agentName: string): Promise<BackupManifest[]> {
+  ensureBackupsDir();
+  const backups: BackupManifest[] = [];
+  
+  if (!fs.existsSync(BACKUPS_DIR)) {
+    return backups;
+  }
+  
+  const files = fs.readdirSync(BACKUPS_DIR);
+  for (const file of files) {
+    if (file.startsWith(agentName) && file.endsWith('.json')) {
+      const filePath = path.join(BACKUPS_DIR, file);
+      try {
+        const manifest = await previewBackup(filePath);
+        if (manifest && manifest.agentName === agentName) {
+          backups.push(manifest);
+        }
+      } catch (error) {
+        console.error(`Failed to read backup ${file}:`, error);
+      }
+    }
+  }
+  
+  backups.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+  return backups;
+}
+
+export async function deleteBackup(filePath: string): Promise<boolean> {
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      return true;
+    }
+    return false;
+  } catch (error) {
+    console.error('Failed to delete backup:', error);
+    return false;
+  }
+}
+
+export function formatBackupSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}

package/src/backup/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Backup Module
+ *
+ * Exports backup functionality.
+ */
+
+export * from './backup.js';