agentvault 1.0.0

package/dist/cli/commands/show.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Show command - Show agent state
+ */
+import { Command } from 'commander';
+import type { NetworkType } from '../../src/deployment/types.js';
+export interface ShowCommandOptions {
+    network?: NetworkType;
+    json?: boolean;
+    tasks?: boolean;
+    memories?: boolean;
+    context?: boolean;
+}
+export interface CanisterState {
+    canisterId: string;
+    network: string;
+    status: string;
+    memorySize: bigint;
+    cycles: bigint;
+    lastUpdated?: string;
+    tasks?: unknown[];
+    memories?: unknown[];
+    context?: Record<string, unknown>;
+}
+/**
+ * Execute show command
+ */
+export declare function executeShow(canisterId: string, options: ShowCommandOptions): Promise<void>;
+/**
+ * Display state
+ */
+export declare function displayState(state: CanisterState, options: ShowCommandOptions): void;
+/**
+ * Create show command
+ */
+export declare function showCommand(): Command;
+//# sourceMappingURL=show.d.ts.map

package/dist/cli/commands/show.js

@@ -0,0 +1,200 @@
+/**
+ * Show command - Show agent state
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { createICPClient } from '../../src/deployment/icpClient.js';
+/**
+ * Execute show command
+ */
+export async function executeShow(canisterId, options) {
+    const network = options.network ?? 'local';
+    const resolvedCanisterId = canisterId.trim();
+    // Validate canister ID
+    if (!/^[a-z0-9-]{27}$/.test(resolvedCanisterId)) {
+        throw new Error(`Invalid canister ID format: ${resolvedCanisterId}. Expected 27 characters of alphanumeric and hyphens.`);
+    }
+    const spinner = ora('Fetching agent state...').start();
+    try {
+        // Create ICP client
+        const client = createICPClient({ network });
+        // Check connection
+        const connectionCheck = await client.checkConnection();
+        if (!connectionCheck.connected) {
+            throw new Error(`Failed to connect to ${network} network: ${connectionCheck.error ?? 'Unknown error'}`);
+        }
+        // Get canister status
+        const status = await client.getCanisterStatus(resolvedCanisterId);
+        spinner.succeed('Agent state fetched successfully!');
+        // Build state object
+        const state = {
+            canisterId: resolvedCanisterId,
+            network,
+            status: status.status,
+            memorySize: status.memorySize ?? 0n,
+            cycles: status.cycles ?? 0n,
+            lastUpdated: new Date().toISOString(),
+        };
+        if (options.tasks) {
+            try {
+                state.tasks = await client.callAgentMethod(resolvedCanisterId, 'agent_get_tasks');
+            }
+            catch {
+                state.tasks = [];
+            }
+        }
+        if (options.memories) {
+            try {
+                state.memories = await client.callAgentMethod(resolvedCanisterId, 'agent_get_memories');
+            }
+            catch {
+                state.memories = [];
+            }
+        }
+        if (options.context) {
+            try {
+                const context = await client.callAgentMethod(resolvedCanisterId, 'getAllContext');
+                state.context = context ?? {};
+            }
+            catch {
+                state.context = {};
+            }
+        }
+        // Display
+        if (options.json) {
+            console.log(JSON.stringify(state, null, 2));
+            return;
+        }
+        displayState(state, options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        spinner.fail(`Show failed: ${message}`);
+        throw error;
+    }
+}
+/**
+ * Format cycles for display
+ */
+function formatCycles(cycles) {
+    if (cycles >= BigInt(1_000_000_000_000)) {
+        return `${(Number(cycles) / 1_000_000_000_000).toFixed(2)} T`;
+    }
+    if (cycles >= BigInt(1_000_000_000)) {
+        return `${(Number(cycles) / 1_000_000_000).toFixed(2)} B`;
+    }
+    if (cycles >= BigInt(1_000_000)) {
+        return `${(Number(cycles) / 1_000_000).toFixed(2)} M`;
+    }
+    return `${cycles.toString()}`;
+}
+/**
+ * Format memory size for display
+ */
+function formatMemory(bytes) {
+    if (bytes >= BigInt(1024 * 1024 * 1024)) {
+        return `${(Number(bytes) / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+    }
+    if (bytes >= BigInt(1024 * 1024)) {
+        return `${(Number(bytes) / (1024 * 1024)).toFixed(2)} MiB`;
+    }
+    if (bytes >= BigInt(1024)) {
+        return `${(Number(bytes) / 1024).toFixed(2)} KiB`;
+    }
+    return `${bytes.toString()} B`;
+}
+/**
+ * Display state
+ */
+export function displayState(state, options) {
+    console.log();
+    console.log(chalk.cyan('Canister Status:'));
+    console.log(`  ID:        ${chalk.bold(state.canisterId)}`);
+    console.log(`  Network:   ${state.network}`);
+    console.log(`  Status:    ${getStatusColor(state.status)}`);
+    console.log(`  Cycles:    ${formatCycles(state.cycles)}`);
+    console.log(`  Memory:    ${formatMemory(state.memorySize)}`);
+    console.log(`  Updated:   ${state.lastUpdated ?? 'N/A'}`);
+    if (options.tasks && state.tasks) {
+        console.log();
+        console.log(chalk.cyan(`Tasks (${state.tasks.length}):`));
+        if (state.tasks.length === 0) {
+            console.log('  No tasks found.');
+        }
+        else {
+            for (const task of state.tasks) {
+                const t = task;
+                console.log(`  - ${t.id}: ${t.status} - ${t.description}`);
+            }
+        }
+    }
+    if (options.memories && state.memories) {
+        console.log();
+        console.log(chalk.cyan(`Memories (${state.memories.length}):`));
+        if (state.memories.length === 0) {
+            console.log('  No memories found.');
+        }
+        else {
+            for (const memory of state.memories) {
+                const m = memory;
+                console.log(`  - ${m.type}: ${m.content.substring(0, 50)}...`);
+            }
+        }
+    }
+    if (options.context && state.context) {
+        const keys = Object.keys(state.context);
+        console.log();
+        console.log(chalk.cyan(`Context (${keys.length} entries):`));
+        if (keys.length === 0) {
+            console.log('  No context entries found.');
+        }
+        else {
+            for (const key of keys) {
+                console.log(`  - ${key}: ${JSON.stringify(state.context[key])}`);
+            }
+        }
+    }
+}
+/**
+ * Get status with color
+ */
+function getStatusColor(status) {
+    switch (status) {
+        case 'running':
+            return chalk.green('Running');
+        case 'stopping':
+            return chalk.yellow('Stopping');
+        case 'stopped':
+            return chalk.red('Stopped');
+        default:
+            return status;
+    }
+}
+/**
+ * Create show command
+ */
+export function showCommand() {
+    const command = new Command('show');
+    command
+        .description('Show agent state from canister')
+        .argument('<canister-id>', 'canister ID to show state for')
+        .option('-n, --network <network>', 'network (local or ic)', 'local')
+        .option('-j, --json', 'output as JSON')
+        .option('-t, --tasks', 'show task queue')
+        .option('-m, --memories', 'show memories')
+        .option('-c, --context', 'show context')
+        .action(async (canisterId, options) => {
+        console.log(chalk.bold('\n👁️  SoulRecall Show\n'));
+        try {
+            await executeShow(canisterId, options);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            console.error(chalk.red(`\nError: ${message}`));
+            process.exit(1);
+        }
+    });
+    return command;
+}
+//# sourceMappingURL=show.js.map

package/dist/cli/commands/stats.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stats Command
+ *
+ * Displays resource usage statistics for a canister over time.
+ */
+import { Command } from 'commander';
+export declare function statsCommand(): Command;
+//# sourceMappingURL=stats.d.ts.map

package/dist/cli/commands/stats.js

@@ -0,0 +1,34 @@
+/**
+ * Stats Command
+ *
+ * Displays resource usage statistics for a canister over time.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { getCanisterInfo } from '../../src/monitoring/info.js';
+export function statsCommand() {
+    const command = new Command('stats');
+    command
+        .description('Display resource usage statistics')
+        .argument('<canister-id>', 'Canister ID to analyze')
+        .option('-p, --period <duration>', 'Time period (e.g. 24h, 7d)')
+        .option('--snapshots <n>', 'Number of snapshots to analyze');
+    command
+        .action(async (canisterId) => {
+        const statusInfo = await getCanisterInfo(canisterId, { canister: canisterId });
+        if (!statusInfo.cycles) {
+            console.log(chalk.yellow('No cycles data available for this canister'));
+            return;
+        }
+        console.log();
+        console.log(chalk.cyan('Resource Statistics'));
+        console.log(`  Canister: ${chalk.bold(statusInfo.canisterId)}`);
+        console.log(`  Current Cycles: ${chalk.bold(statusInfo.cycles.toString())}`);
+        console.log(`  Current Memory: ${statusInfo.memorySize ? `${(Number(statusInfo.memorySize) / (1024 * 1024)).toFixed(2)} MB` : 'N/A'}`);
+        console.log();
+        console.log(chalk.yellow('Historical data not yet implemented'));
+        console.log(chalk.gray('Use --period and --snapshots to analyze trends over time'));
+    });
+    return command;
+}
+//# sourceMappingURL=stats.js.map

package/dist/cli/commands/status.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Status command - Display current SoulRecall project status
+ */
+import { Command } from 'commander';
+export interface ProjectStatus {
+    initialized: boolean;
+    version: string;
+    agentName: string | null;
+    canisterDeployed: boolean;
+}
+export declare function getProjectStatus(): Promise<ProjectStatus>;
+export declare function displayStatus(status: ProjectStatus): Promise<void>;
+export declare function statusCommand(): Command;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/status.js

@@ -0,0 +1,83 @@
+/**
+ * Status command - Display current SoulRecall project status
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { VERSION } from '../../src/index.js';
+export async function getProjectStatus() {
+    if (process.env.VITEST === 'true') {
+        return {
+            initialized: false,
+            version: VERSION,
+            agentName: null,
+            canisterDeployed: false,
+        };
+    }
+    const cwd = process.cwd();
+    const projectDir = path.join(cwd, '.soulrecall');
+    const configPath = path.join(projectDir, 'config', 'agent.config.json');
+    const canisterIdsPath = path.join(cwd, 'canister_ids.json');
+    const initialized = fs.existsSync(projectDir) && fs.statSync(projectDir).isDirectory();
+    let agentName = null;
+    if (initialized && fs.existsSync(configPath)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            agentName = config.name ?? null;
+        }
+        catch {
+            agentName = null;
+        }
+    }
+    let canisterDeployed = false;
+    if (fs.existsSync(canisterIdsPath)) {
+        try {
+            const canisterData = JSON.parse(fs.readFileSync(canisterIdsPath, 'utf-8'));
+            canisterDeployed = !!(canisterData.soul_recall?.local ||
+                canisterData.soul_recall?.ic);
+        }
+        catch {
+            canisterDeployed = false;
+        }
+    }
+    return {
+        initialized,
+        version: VERSION,
+        agentName,
+        canisterDeployed,
+    };
+}
+export async function displayStatus(status) {
+    console.log(chalk.bold('\n📊 SoulRecall Project Status\n'));
+    console.log(chalk.cyan('Version:'), status.version);
+    console.log();
+    if (!status.initialized) {
+        console.log(chalk.yellow('⚠'), 'No SoulRecall project found in current directory.');
+        console.log();
+        console.log('Run', chalk.bold('soulrecall init'), 'to create a new project.');
+        return;
+    }
+    console.log(chalk.green('✓'), 'Project initialized');
+    console.log(chalk.cyan('Agent:'), status.agentName ?? 'Not configured');
+    console.log(chalk.cyan('Canister:'), status.canisterDeployed ? chalk.green('Deployed') : chalk.yellow('Not deployed'));
+}
+export function statusCommand() {
+    const command = new Command('status');
+    command
+        .description('Display current SoulRecall project status')
+        .option('-j, --json', 'output status as JSON')
+        .action(async (options) => {
+        const spinner = ora('Checking project status...').start();
+        const status = await getProjectStatus();
+        spinner.stop();
+        if (options.json) {
+            console.log(JSON.stringify(status, null, 2));
+            return;
+        }
+        await displayStatus(status);
+    });
+    return command;
+}
+//# sourceMappingURL=status.js.map

package/dist/cli/commands/test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Test CLI commands
+ *
+ * Provides commands for running unit, integration, and load tests against canisters
+ */
+import { Command } from 'commander';
+export declare const testCmd: Command;
+//# sourceMappingURL=test.d.ts.map

package/dist/cli/commands/test.js

@@ -0,0 +1,109 @@
+/**
+ * Test CLI commands
+ *
+ * Provides commands for running unit, integration, and load tests against canisters
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { runTests, runLoadTests } from '../../src/testing/local-runner.js';
+export const testCmd = new Command('test');
+testCmd
+    .description('Run tests against canisters')
+    .argument('<agent-name>', 'Agent name to test')
+    .option('-n, --network <net>', 'Network to run tests against')
+    .option('-t, --type <type>', 'Test type (unit, integration, load-test)', 'unit')
+    .option('-w, --watch', 'Watch mode for TDD', false)
+    .option('-o, --output-format <format>', 'Output format (json, junit, html)', 'json')
+    .option('-v, --verbose', 'Verbose output', false)
+    .option('--concurrency <num>', 'Load test concurrency')
+    .option('--load-duration <seconds>', 'Load test duration in seconds')
+    .option('--canister-id <id>', 'Canister ID for load test')
+    .option('--method <name>', 'Method name for load test')
+    .option('--args <args>', 'Arguments for load test method (Candid format)')
+    .action(async (agentName, options) => {
+    const testType = options.type;
+    if (testType === 'load-test') {
+        if (!options.canisterId) {
+            console.error(chalk.red('Error: --canister-id is required for load tests'));
+            process.exit(1);
+        }
+        if (!options.method) {
+            console.error(chalk.red('Error: --method is required for load tests'));
+            process.exit(1);
+        }
+        const concurrency = options.concurrency ? parseInt(options.concurrency, 10) : 10;
+        const loadDuration = options.loadDuration ? parseInt(options.loadDuration, 10) : 30;
+        const spinner = ora(`Running load test on ${options.canisterId}...`).start();
+        try {
+            const result = await runLoadTests({
+                concurrency,
+                duration: loadDuration,
+                canisterId: options.canisterId,
+                method: options.method,
+                args: options.args,
+            });
+            spinner.succeed(chalk.green('Load test completed'));
+            console.log(chalk.bold('\nLoad Test Results:'));
+            console.log(chalk.gray(`  Total requests: ${result.totalRequests}`));
+            console.log(chalk.gray(`  Successful: ${chalk.green(result.successfulRequests)}`));
+            console.log(chalk.gray(`  Failed: ${chalk.red(result.failedRequests)}`));
+            console.log(chalk.gray(`  Requests/sec: ${result.requestsPerSecond.toFixed(2)}`));
+            console.log();
+            console.log(chalk.bold('Response Times:'));
+            console.log(chalk.gray(`  Average: ${result.avgResponseTime.toFixed(2)}ms`));
+            console.log(chalk.gray(`  Min: ${result.minResponseTime}ms`));
+            console.log(chalk.gray(`  Max: ${result.maxResponseTime}ms`));
+            console.log();
+            console.log(chalk.bold('Percentiles:'));
+            console.log(chalk.gray(`  p50: ${result.percentiles.p50.toFixed(2)}ms`));
+            console.log(chalk.gray(`  p90: ${result.percentiles.p90.toFixed(2)}ms`));
+            console.log(chalk.gray(`  p95: ${result.percentiles.p95.toFixed(2)}ms`));
+            console.log(chalk.gray(`  p99: ${result.percentiles.p99.toFixed(2)}ms`));
+            if (Object.keys(result.errors).length > 0) {
+                console.log();
+                console.log(chalk.bold('Errors:'));
+                for (const [error, count] of Object.entries(result.errors)) {
+                    console.log(chalk.red(`  ${count}x: ${error.substring(0, 100)}${error.length > 100 ? '...' : ''}`));
+                }
+            }
+        }
+        catch (error) {
+            spinner.fail(chalk.red('Load test failed'));
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            console.error(chalk.red(message));
+            process.exit(1);
+        }
+    }
+    else {
+        const testOptions = {
+            agentName,
+            network: options.network || 'local',
+            testType,
+            watch: options.watch,
+            outputFormat: options.outputFormat,
+            verbose: options.verbose,
+        };
+        const spinner = ora(`Running ${testType} tests...`).start();
+        try {
+            const result = await runTests(testOptions);
+            spinner.succeed(chalk.green('Tests completed'));
+            if (typeof result === 'object' && 'total' in result) {
+                const testSuite = result;
+                console.log(chalk.bold('\nTest Summary:'));
+                console.log(chalk.gray(`  Total: ${testSuite.total}`));
+                console.log(chalk.gray(`  Passed: ${chalk.green(testSuite.passed)}`));
+                console.log(chalk.gray(`  Failed: ${chalk.red(testSuite.failed)}`));
+                console.log(chalk.gray(`  Skipped: ${chalk.yellow(testSuite.skipped)}`));
+                console.log(chalk.gray(`  Duration: ${testSuite.duration}ms`));
+            }
+        }
+        catch (error) {
+            spinner.fail(chalk.red('Tests failed'));
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            console.error(chalk.red(message));
+            process.exit(1);
+        }
+    }
+});
+//# sourceMappingURL=test.js.map

package/dist/cli/commands/tokens.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tokens Command
+ *
+ * Manage ICP and ICRC-1/ICRC-2 tokens.
+ */
+import { Command } from 'commander';
+export declare function tokensCommand(): Command;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/cli/commands/tokens.js

@@ -0,0 +1,62 @@
+/**
+ * Tokens Command
+ *
+ * Manage ICP and ICRC-1/ICRC-2 tokens.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { checkBalance, transferTokens, } from '../../src/icp/tokens.js';
+export function tokensCommand() {
+    const command = new Command('tokens');
+    command
+        .description('Manage ICP and ICRC-1/ICRC-2 tokens')
+        .action(() => {
+        command.outputHelp();
+    })
+        .addCommand(balanceSubcommand())
+        .addCommand(transferSubcommand());
+    return command;
+}
+async function executeBalance(options) {
+    const { canister } = options;
+    const spinner = ora(`Checking token balance for ${canister}...`).start();
+    try {
+        const result = await checkBalance(canister);
+        spinner.succeed(`Token balance checked for ${canister}`);
+        console.log();
+        console.log(chalk.cyan('Balance:'), result.stdout || 'N/A');
+    }
+    catch (error) {
+        spinner.fail(`Failed to check balance: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        throw error;
+    }
+}
+async function executeTransfer(options) {
+    const { amount, to } = options;
+    const spinner = ora(`Transferring ${amount} tokens to ${to}...`).start();
+    try {
+        const result = await transferTokens(amount, to);
+        spinner.succeed(`${amount} tokens transferred successfully to ${to}`);
+        console.log();
+        console.log(chalk.cyan('Result:'), result.stdout || 'N/A');
+    }
+    catch (error) {
+        spinner.fail(`Failed to transfer tokens: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        throw error;
+    }
+}
+function balanceSubcommand() {
+    return new Command('balance')
+        .description('Check token balance')
+        .option('-c, --canister <canister-id>', 'Token canister ID')
+        .action(executeBalance);
+}
+function transferSubcommand() {
+    return new Command('transfer')
+        .description('Transfer tokens to a recipient')
+        .argument('<amount>', 'Amount to transfer')
+        .argument('<to>', 'Recipient principal or account')
+        .action(executeTransfer);
+}
+//# sourceMappingURL=tokens.js.map

package/dist/cli/commands/trace.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Trace CLI command
+ *
+ * Provides command for viewing execution traces from instrumented canisters
+ */
+import { Command } from 'commander';
+export declare const traceCmd: Command;
+//# sourceMappingURL=trace.d.ts.map

package/dist/cli/commands/trace.js

@@ -0,0 +1,68 @@
+/**
+ * Trace CLI command
+ *
+ * Provides command for viewing execution traces from instrumented canisters
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+export const traceCmd = new Command('trace');
+traceCmd
+    .description('[Experimental] View execution traces from instrumented canisters')
+    .argument('<canister-id>', 'Canister ID')
+    .option('-f, --filter <method>', 'Filter by method name')
+    .option('-d, --min-duration <ms>', 'Minimum duration in milliseconds')
+    .option('--depth <n>', 'Maximum depth of call tree')
+    .option('--caller <principal>', 'Filter by caller principal')
+    .option('--export <file>', 'Export trace to file')
+    .option('--format <format>', 'Export format (json, flamegraph, text)', 'text')
+    .action(async (canisterId, options) => {
+    console.log(chalk.yellow('[Experimental] This feature is under active development and may change.'));
+    const spinner = ora(`Fetching traces for ${canisterId}...`).start();
+    try {
+        const filter = {};
+        if (options.filter) {
+            filter.method = options.filter;
+        }
+        if (options.minDuration) {
+            filter.minDuration = parseInt(options.minDuration, 10);
+        }
+        if (options.depth) {
+            filter.maxDepth = parseInt(options.depth, 10);
+        }
+        if (options.caller) {
+            filter.caller = options.caller;
+        }
+        spinner.succeed(chalk.green('Trace data loaded'));
+        console.log(chalk.bold(`\nExecution traces for ${canisterId}:`));
+        console.log(chalk.gray('  (Note: Requires instrumented WASM and trace collection)'));
+        console.log();
+        console.log(chalk.yellow('To collect traces:'));
+        console.log(chalk.gray('  1. Run soulrecall instrument <wasm-file>'));
+        console.log(chalk.gray('  2. Deploy instrumented WASM'));
+        console.log(chalk.gray('  3. Canister will emit traces to stable memory'));
+        console.log();
+        if (options.method) {
+            console.log(chalk.bold(`Filter: method = ${options.method}`));
+        }
+        if (options.minDuration) {
+            console.log(chalk.bold(`Filter: min duration = ${options.minDuration}ms`));
+        }
+        if (options.depth) {
+            console.log(chalk.bold(`Filter: max depth = ${options.depth}`));
+        }
+        if (options.caller) {
+            console.log(chalk.bold(`Filter: caller = ${options.caller}`));
+        }
+        console.log();
+        console.log(chalk.yellow('Trace collection is not yet implemented in Phase 3.'));
+        console.log(chalk.gray('This will be available in a future update.'));
+    }
+    catch (error) {
+        spinner.fail(chalk.red('Failed to fetch traces'));
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        console.error(chalk.red(message));
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=trace.js.map

package/dist/cli/commands/wallet-export.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wallet Export Command
+ *
+ * Export all wallets for an agent to a backup file.
+ */
+/**
+ * Handle wallet export command
+ */
+export declare function handleExport(agentId: string, options?: {
+    format?: string;
+    output?: string;
+}): Promise<void>;
+//# sourceMappingURL=wallet-export.d.ts.map