agentvault 1.0.0

package/src/cloud-storage/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Cloud Storage Types
+ *
+ * Types for the cloud storage backup feature that lets users
+ * archive and restore AgentVault data using consumer cloud
+ * storage providers (Google Drive, iCloud, Dropbox, etc.)
+ * via their local sync directories — no crypto required.
+ */
+
+/**
+ * Supported cloud storage providers detected via local sync directories.
+ */
+export type CloudProvider =
+  | 'google-drive'
+  | 'icloud-drive'
+  | 'dropbox'
+  | 'onedrive'
+  | 'custom';
+
+/**
+ * A detected cloud provider with its local sync path.
+ */
+export interface DetectedProvider {
+  provider: CloudProvider;
+  label: string;
+  path: string;
+  available: boolean;
+}
+
+/**
+ * Configuration for cloud backup destination.
+ */
+export interface CloudBackupConfig {
+  provider: CloudProvider;
+  basePath: string;
+  subdirectory: string;
+}
+
+/**
+ * What to include in a cloud backup archive.
+ */
+export interface CloudArchiveOptions {
+  agentName?: string;
+  includeConfigs: boolean;
+  includeWallets: boolean;
+  includeBackups: boolean;
+  includeNetworks: boolean;
+}
+
+/**
+ * Metadata written alongside the archive for identification and integrity.
+ */
+export interface CloudArchiveManifest {
+  version: string;
+  createdAt: string;
+  platform: string;
+  hostname: string;
+  agentVaultVersion: string;
+  agentName?: string;
+  components: string[];
+  files: CloudArchiveFileEntry[];
+  checksum: string;
+}
+
+/**
+ * Entry for a single file within the archive manifest.
+ */
+export interface CloudArchiveFileEntry {
+  relativePath: string;
+  sizeBytes: number;
+  checksum: string;
+}
+
+/**
+ * Result of an archive operation.
+ */
+export interface CloudArchiveResult {
+  success: boolean;
+  archivePath?: string;
+  manifestPath?: string;
+  fileCount?: number;
+  totalBytes?: number;
+  error?: string;
+}
+
+/**
+ * Result of a restore operation.
+ */
+export interface CloudRestoreResult {
+  success: boolean;
+  restoredFiles?: number;
+  components?: string[];
+  warnings: string[];
+  error?: string;
+}
+
+/**
+ * A discovered archive available for restore.
+ */
+export interface DiscoveredArchive {
+  manifestPath: string;
+  archivePath: string;
+  manifest: CloudArchiveManifest;
+}

package/src/debugging/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Debugging module
+ */
+
+export * from './types.js';
+export * from './logs.js';

package/src/debugging/logs.ts

@@ -0,0 +1,193 @@
+/**
+ * Log aggregation for canister debugging
+ *
+ * Collects, stores, and queries logs from canisters
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import type { LogEntry, LogLevel } from './types.js';
+
+const AGENTVAULT_DIR = path.join(os.homedir(), '.agentvault');
+const LOGS_DIR = path.join(AGENTVAULT_DIR, 'logs');
+
+/**
+ * Ensure logs directory exists
+ */
+function ensureLogsDir(): void {
+  if (!fs.existsSync(AGENTVAULT_DIR)) {
+    fs.mkdirSync(AGENTVAULT_DIR, { recursive: true });
+  }
+  if (!fs.existsSync(LOGS_DIR)) {
+    fs.mkdirSync(LOGS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get logs directory for a specific canister
+ */
+function getCanisterLogsDir(canisterId: string): string {
+  ensureLogsDir();
+  const canisterDir = path.join(LOGS_DIR, canisterId);
+  if (!fs.existsSync(canisterDir)) {
+    fs.mkdirSync(canisterDir, { recursive: true });
+  }
+  return canisterDir;
+}
+
+/**
+ * Get log file path for a canister and date
+ */
+function getLogFilePath(canisterId: string, date?: Date): string {
+  const logsDir = getCanisterLogsDir(canisterId);
+  const logDate = date || new Date();
+  const dateStr = logDate.toISOString().split('T')[0];
+  return path.join(logsDir, `${dateStr}.jsonl`);
+}
+
+/**
+ * Parse log line from canister output
+ */
+function parseLogLine(line: string, canisterId: string): LogEntry | null {
+  try {
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    
+    return {
+      timestamp: new Date(parsed.timestamp as string),
+      level: (parsed.level as LogLevel) || 'info',
+      message: (parsed.message as string) || '',
+      canisterId,
+      method: parsed.method as string | undefined,
+      context: parsed.context as Record<string, unknown> | undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect logs from canister output
+ */
+export async function collectLogs(canisterId: string, output: string): Promise<LogEntry[]> {
+  const logs: LogEntry[] = [];
+  const lines = output.split('\n');
+  
+  for (const line of lines) {
+    if (line.trim()) {
+      const logEntry = parseLogLine(line, canisterId);
+      if (logEntry) {
+        logs.push(logEntry);
+      }
+    }
+  }
+  
+  return logs;
+}
+
+/**
+ * Store log entries to disk
+ */
+export async function storeLogs(canisterId: string, logs: LogEntry[]): Promise<void> {
+  const logFilePath = getLogFilePath(canisterId);
+  const lines = logs.map((log) => JSON.stringify(log)).join('\n');
+  
+  fs.appendFileSync(logFilePath, lines + '\n', 'utf8');
+}
+
+/**
+ * Retrieve logs for a canister with optional filtering
+ */
+export async function getLogs(
+  canisterId: string,
+  options: {
+    since?: Date;
+    level?: LogLevel;
+    pattern?: string;
+    limit?: number;
+  } = {},
+): Promise<LogEntry[]> {
+  const logsDir = getCanisterLogsDir(canisterId);
+  const files = fs.readdirSync(logsDir)
+    .filter((f) => f.endsWith('.jsonl'))
+    .sort()
+    .reverse();
+  
+  const allLogs: LogEntry[] = [];
+  
+  for (const file of files) {
+    const filePath = path.join(logsDir, file);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    
+    for (const line of lines) {
+      if (line.trim()) {
+        const log = parseLogLine(line, canisterId);
+        if (log) {
+          allLogs.push(log);
+        }
+      }
+    }
+    
+    if (options.since) {
+      const fileDate = new Date(file.replace('.jsonl', ''));
+      if (fileDate < options.since) {
+        break;
+      }
+    }
+  }
+  
+  const filteredLogs = allLogs.filter((log) => {
+    if (options.since && log.timestamp < options.since) {
+      return false;
+    }
+    if (options.level && log.level !== options.level) {
+      return false;
+    }
+    if (options.pattern && !log.message.includes(options.pattern)) {
+      return false;
+    }
+    return true;
+  });
+  
+  if (options.limit) {
+    return filteredLogs.slice(-options.limit);
+  }
+  
+  return filteredLogs.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+}
+
+/**
+ * Export logs to a file
+ */
+export async function exportLogs(
+  canisterId: string,
+  outputPath: string,
+  format: 'json' | 'csv' = 'json',
+): Promise<void> {
+  const logs = await getLogs(canisterId);
+  
+  if (format === 'json') {
+    fs.writeFileSync(outputPath, JSON.stringify(logs, null, 2), 'utf8');
+  } else if (format === 'csv') {
+    const headers = 'timestamp,level,message,canisterId,method,context\n';
+    const rows = logs.map((log) => {
+      const context = log.context ? JSON.stringify(log.context).replace(/"/g, '""') : '';
+      return `"${log.timestamp.toISOString()}","${log.level}","${log.message.replace(/"/g, '""')}","${log.canisterId}","${log.method || ''}","${context}"`;
+    }).join('\n');
+    
+    fs.writeFileSync(outputPath, headers + rows, 'utf8');
+  }
+}
+
+/**
+ * Clear logs for a canister
+ */
+export async function clearLogs(canisterId: string): Promise<void> {
+  const logsDir = getCanisterLogsDir(canisterId);
+  const files = fs.readdirSync(logsDir);
+  
+  for (const file of files) {
+    fs.unlinkSync(path.join(logsDir, file));
+  }
+}

package/src/debugging/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Types for debugging and instrumentation functionality
+ */
+
+/** Log level */
+export type LogLevel = 'info' | 'warning' | 'error' | 'debug';
+
+/** Log entry from canister or system */
+export interface LogEntry {
+  /** Log timestamp */
+  timestamp: Date;
+  /** Log level */
+  level: LogLevel;
+  /** Log message */
+  message: string;
+  /** Source canister ID */
+  canisterId: string;
+  /** Method that generated the log (if applicable) */
+  method?: string;
+  /** Additional context */
+  context?: Record<string, unknown>;
+}
+
+/** Trace filter options */
+export interface TraceFilter {
+  /** Filter by method name */
+  method?: string;
+  /** Minimum duration in milliseconds */
+  minDuration?: number;
+  /** Maximum depth of the call tree */
+  maxDepth?: number;
+  /** Filter by caller principal */
+  caller?: string;
+}
+
+/** Method statistics for profiling */
+export interface MethodStats {
+  /** Number of calls */
+  count: number;
+  /** Total duration in milliseconds */
+  totalDuration: number;
+  /** Average duration in milliseconds */
+  avgDuration: number;
+  /** Maximum duration in milliseconds */
+  maxDuration: number;
+}
+
+/** Result of profiling a canister */
+export interface ProfileResult {
+  /** Number of samples collected */
+  samples: number;
+  /** Duration of profiling in seconds */
+  duration: number;
+  /** Statistics per method */
+  methodStats: Map<string, MethodStats>;
+  /** Memory snapshots taken during profiling */
+  memorySnapshots: number[];
+}
+
+/** Instrument result */
+export interface InstrumentResult {
+  /** Whether instrumentation succeeded */
+  success: boolean;
+  /** Path to instrumented WASM */
+  outputPath: string;
+  /** Any warnings from instrumentation */
+  warnings: string[];
+}
+
+/** Trace export format */
+export type TraceExportFormat = 'json' | 'flamegraph' | 'text';
+
+/** Dashboard metric types */
+export interface DashboardMetrics {
+  /** Current cycles balance */
+  cycles: bigint;
+  /** Memory usage in bytes */
+  memory: bigint;
+  /** Requests per second */
+  requestRate: number;
+  /** Error rate */
+  errorRate: number;
+}
+
+/** Alert severity levels */
+export type AlertSeverity = 'info' | 'warning' | 'error' | 'critical';
+
+/** Alert entry */
+export interface AlertEntry {
+  /** Alert timestamp */
+  timestamp: Date;
+  /** Alert severity */
+  severity: AlertSeverity;
+  /** Alert message */
+  message: string;
+  /** Related canister ID */
+  canisterId: string;
+  /** Alert type/category */
+  type: string;
+}

package/src/deployment/deployer.ts

@@ -0,0 +1,274 @@
+/**
+ * Agent Deployer
+ *
+ * Main orchestrator for the ICP canister deployment pipeline.
+ * Coordinates validation, client setup, and deployment operations.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type {
+  DeployOptions,
+  DeployResult,
+  DeploymentError,
+  CanisterInfo,
+  NetworkType,
+  DeploymentStatus,
+} from './types.js';
+import { createICPClient } from './icpClient.js';
+import { detectToolchain } from '../icp/tool-detector.js';
+import * as icpcli from '../icp/icpcli.js';
+import { getEnvironment } from '../icp/environment.js';
+
+/**
+ * Extract agent name from WASM file path
+ */
+function extractAgentName(wasmPath: string): string {
+  const basename = path.basename(wasmPath);
+  // Remove .wasm extension
+  return basename.replace(/\.wasm$/, '');
+}
+
+/**
+ * Validate deployment options
+ */
+export function validateDeployOptions(options: DeployOptions): {
+  valid: boolean;
+  errors: DeploymentError[];
+  warnings: string[];
+} {
+  const errors: DeploymentError[] = [];
+  const warnings: string[] = [];
+
+  // Validate WASM path using client
+  const client = createICPClient({ network: options.network });
+  const wasmValidation = client.validateWasmPath(options.wasmPath);
+  if (!wasmValidation.valid) {
+    errors.push({
+      code: 'INVALID_WASM',
+      message: wasmValidation.error!,
+    });
+  }
+
+  // Validate network - requires standard network name or an explicit environment config
+  const knownNetworks = ['local', 'ic', 'mainnet', 'dev', 'staging', 'production'];
+  if (!knownNetworks.includes(options.network)) {
+    errors.push({
+      code: 'INVALID_NETWORK',
+      message: `Network '${options.network}' is not a standard name. Ensure it is defined in your icp.yaml.`,
+    });
+  }
+
+  // Warn about mainnet deployment
+  if (options.network === 'ic' && !options.skipConfirmation) {
+    warnings.push(
+      'Deploying to IC mainnet will consume cycles. Ensure you have sufficient balance.'
+    );
+  }
+
+  // Warn about upgrade without canister ID check
+  if (options.canisterId) {
+    warnings.push(`Upgrading existing canister: ${options.canisterId}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Get deployment preview/summary
+ *
+ * Useful for dry-run functionality
+ */
+export function getDeploySummary(options: DeployOptions): {
+  agentName: string;
+  wasmPath: string;
+  wasmHash: string;
+  wasmSize: number;
+  network: NetworkType;
+  isUpgrade: boolean;
+  canisterId?: string;
+  validation: ReturnType<typeof validateDeployOptions>;
+} {
+  const validation = validateDeployOptions(options);
+
+  // Calculate WASM hash if file exists
+  let wasmHash = '';
+  let wasmSize = 0;
+  if (validation.valid) {
+    try {
+      const client = createICPClient({ network: options.network });
+      wasmHash = client.calculateWasmHash(options.wasmPath);
+      wasmSize = fs.statSync(options.wasmPath).size;
+    } catch {
+      // File doesn't exist or can't be read
+    }
+  }
+
+  return {
+    agentName: extractAgentName(options.wasmPath),
+    wasmPath: options.wasmPath,
+    wasmHash,
+    wasmSize,
+    network: options.network,
+    isUpgrade: !!options.canisterId,
+    canisterId: options.canisterId,
+    validation,
+  };
+}
+
+/**
+ * Deploy an agent to ICP
+ *
+ * This is the main entry point for the deployment pipeline.
+ * Uses auto-detection to choose between icp-cli and the @dfinity/agent SDK.
+ *
+ * Priority: icp-cli > @dfinity/agent SDK (with dfx fallback)
+ *
+ * @param options - Deployment options
+ * @returns Deployment result with canister info
+ */
+export async function deployAgent(options: DeployOptions): Promise<DeployResult> {
+  // Validate options
+  const validation = validateDeployOptions(options);
+  if (!validation.valid) {
+    const errorMessages = validation.errors.map((e) => e.message).join('; ');
+    throw new Error(`Deployment validation failed: ${errorMessages}`);
+  }
+
+  // Detect available toolchain
+  const toolchain = await detectToolchain();
+
+  // Determine which tool to use
+  if (toolchain.icp.available && (options.environment || options.identity)) {
+    // Use icp-cli when explicitly requesting environments or identity features
+    return deployWithIcpCli(options, validation.warnings);
+  } else if (toolchain.preferredDeployTool === 'icp') {
+    // Prefer icp-cli when available
+    return deployWithIcpCli(options, validation.warnings);
+  } else {
+    // Fall back to @dfinity/agent SDK
+    return deployWithSdk(options, validation.warnings);
+  }
+}
+
+/**
+ * Deploy using icp-cli tool.
+ */
+async function deployWithIcpCli(
+  options: DeployOptions,
+  warnings: string[],
+): Promise<DeployResult> {
+  // Resolve environment from options or network
+  const envName = options.environment ?? options.network;
+  const envConfig = getEnvironment(envName);
+  const identity = options.identity ?? envConfig.identity;
+
+  // Determine deploy mode
+  const mode = options.mode ?? (options.canisterId ? 'upgrade' : 'auto');
+
+  const result = await icpcli.deploy({
+    environment: envName,
+    identity,
+    mode,
+    projectRoot: options.projectRoot,
+  });
+
+  if (!result.success) {
+    throw new Error(`icp-cli deploy failed: ${result.stderr || result.stdout}`);
+  }
+
+  // Parse canister ID from output (best effort)
+  const canisterIdMatch = result.stdout.match(/([a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{5}-[a-z0-9]{3})/);
+  const canisterId = canisterIdMatch?.[1] ?? options.canisterId ?? 'unknown';
+
+  const canisterInfo: CanisterInfo = {
+    canisterId,
+    network: options.network,
+    agentName: extractAgentName(options.wasmPath),
+    deployedAt: new Date(),
+  };
+
+  return {
+    canister: canisterInfo,
+    isUpgrade: mode === 'upgrade',
+    warnings: [...warnings, `Deployed via icp-cli (environment: ${envName})`],
+    deployTool: 'icp',
+  };
+}
+
+/**
+ * Deploy using @dfinity/agent SDK (original implementation).
+ */
+async function deployWithSdk(
+  options: DeployOptions,
+  warnings: string[],
+): Promise<DeployResult> {
+  // Create ICP client
+  const client = createICPClient({
+    network: options.network,
+    identity: options.identityPath,
+  });
+
+  // Check network connection
+  const connectionCheck = await client.checkConnection();
+  if (!connectionCheck.connected) {
+    throw new Error(
+      `Failed to connect to ${options.network} network: ${connectionCheck.error ?? 'Unknown error'}`
+    );
+  }
+
+  // Deploy the WASM
+  const deployResult = await client.deploy(options.wasmPath, options.canisterId);
+
+  // Build canister info
+  const canisterInfo: CanisterInfo = {
+    canisterId: deployResult.canisterId,
+    network: options.network,
+    agentName: extractAgentName(options.wasmPath),
+    deployedAt: new Date(),
+    wasmHash: deployResult.wasmHash,
+  };
+
+  return {
+    canister: canisterInfo,
+    isUpgrade: deployResult.isUpgrade,
+    cyclesUsed: deployResult.cyclesUsed,
+    warnings,
+    deployTool: 'sdk',
+  };
+}
+
+/**
+ * Check if a canister exists and get its status
+ */
+export async function getCanisterStatus(
+  canisterId: string,
+  network: NetworkType
+): Promise<{
+  exists: boolean;
+  status?: DeploymentStatus;
+  memorySize?: bigint;
+  cycles?: bigint;
+}> {
+  const client = createICPClient({ network });
+
+  try {
+    const status = await client.getCanisterStatus(canisterId);
+    if (!status.exists) {
+      return { exists: false };
+    }
+
+    return {
+      exists: status.exists,
+      status: status.status,
+      memorySize: status.memorySize,
+      cycles: status.cycles,
+    };
+  } catch {
+    return { exists: false };
+  }
+}