agentvault 1.0.0

package/src/packaging/serializer.ts

@@ -0,0 +1,260 @@
+/**
+ * Agent State Serializer
+ *
+ * This module handles serialization and deserialization of agent state
+ * for storage in canisters and local files.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { AgentConfig } from './types.js';
+
+/**
+ * Agent state schema version
+ */
+export const SCHEMA_VERSION = '1.0.0';
+
+/**
+ * Memory item in agent state
+ */
+export interface Memory {
+  id: string;
+  type: 'fact' | 'user_preference' | 'task_result';
+  content: unknown;
+  timestamp: number;
+  importance: number;
+}
+
+/**
+ * Task in agent queue
+ */
+export interface Task {
+  id: string;
+  description: string;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  result?: unknown;
+  timestamp: number;
+}
+
+/**
+ * Agent state stored in canister
+ */
+export interface AgentState {
+  config: AgentConfig;
+  memories: Memory[];
+  tasks: Task[];
+  context: Map<string, unknown>;
+  version: string;
+  lastUpdated: number;
+}
+
+/**
+ * Serialized agent state (for storage/transmission)
+ */
+export interface SerializedAgentState {
+  $schema: string;
+  version: string;
+  agent: {
+    name: string;
+    type: string;
+    version?: string;
+  };
+  metadata: {
+    createdAt: string;
+    sourcePath: string;
+    entryPoint?: string;
+  };
+  state: {
+    initialized: boolean;
+    data: {
+      memories?: Memory[];
+      tasks?: Task[];
+      context?: Record<string, unknown>;
+    };
+  };
+}
+
+/**
+ * Serialization options
+ */
+export interface SerializationOptions {
+  pretty?: boolean;
+  includeMemories?: boolean;
+  includeTasks?: boolean;
+  includeContext?: boolean;
+}
+
+/**
+ * Default serialization options
+ */
+const DEFAULT_OPTIONS: SerializationOptions = {
+  pretty: true,
+  includeMemories: true,
+  includeTasks: true,
+  includeContext: true,
+};
+
+/**
+ * Serialize agent state to JSON
+ */
+export function serializeState(
+  state: AgentState,
+  options: SerializationOptions = {}
+): string {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+
+  const serialized: SerializedAgentState = {
+    $schema: `https://agentvault.dev/schemas/agent-state-v${SCHEMA_VERSION}.json`,
+    version: SCHEMA_VERSION,
+    agent: {
+      name: state.config.name,
+      type: state.config.type,
+      version: state.config.version,
+    },
+    metadata: {
+      createdAt: new Date().toISOString(),
+      sourcePath: state.config.sourcePath,
+      entryPoint: state.config.entryPoint,
+    },
+    state: {
+      initialized: state.memories.length > 0 || state.tasks.length > 0,
+      data: {},
+    },
+  };
+
+  if (opts.includeMemories) {
+    serialized.state.data.memories = state.memories;
+  }
+
+  if (opts.includeTasks) {
+    serialized.state.data.tasks = state.tasks;
+  }
+
+  if (opts.includeContext) {
+    serialized.state.data.context = mapToObject(state.context);
+  }
+
+  return JSON.stringify(serialized, null, opts.pretty ? 2 : 0);
+}
+
+/**
+ * Deserialize agent state from JSON
+ */
+export function deserializeState(json: string): AgentState {
+  const serialized = JSON.parse(json) as SerializedAgentState;
+
+  return {
+    config: {
+      name: serialized.agent.name,
+      type: serialized.agent.type as 'clawdbot' | 'goose' | 'cline' | 'generic',
+      sourcePath: serialized.metadata.sourcePath,
+      entryPoint: serialized.metadata.entryPoint,
+      version: serialized.agent.version,
+    },
+    memories: serialized.state.data.memories ?? [],
+    tasks: serialized.state.data.tasks ?? [],
+    context: new Map(Object.entries(serialized.state.data.context ?? {})),
+    version: serialized.version,
+    lastUpdated: Date.now(),
+  };
+}
+
+/**
+ * Write serialized state to file
+ */
+export async function writeStateFile(
+  state: AgentState,
+  filePath: string,
+  options: SerializationOptions = {}
+): Promise<void> {
+  const serialized = serializeState(state, options);
+
+  // Ensure directory exists
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Write file
+  fs.writeFileSync(filePath, serialized, 'utf-8');
+}
+
+/**
+ * Read state from file
+ */
+export async function readStateFile(filePath: string): Promise<AgentState> {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return deserializeState(content);
+}
+
+/**
+ * Convert Map to plain object
+ */
+function mapToObject<T>(map: Map<string, T>): Record<string, T> {
+  const obj: Record<string, T> = {};
+  for (const [key, value] of map.entries()) {
+    obj[key] = value;
+  }
+  return obj;
+}
+
+/**
+ * Create empty agent state
+ */
+export function createEmptyState(config: AgentConfig): AgentState {
+  return {
+    config,
+    memories: [],
+    tasks: [],
+    context: new Map(),
+    version: SCHEMA_VERSION,
+    lastUpdated: Date.now(),
+  };
+}
+
+/**
+ * Merge two agent states
+ */
+export function mergeStates(
+  base: AgentState,
+  updates: Partial<AgentState>
+): AgentState {
+  const merged: AgentState = {
+    ...base,
+    config: updates.config ?? base.config,
+    memories: updates.memories ?? base.memories,
+    tasks: updates.tasks ?? base.tasks,
+    context: updates.context ?? base.context,
+    version: updates.version ?? base.version,
+    lastUpdated: updates.lastUpdated ?? Date.now(),
+  };
+
+  return merged;
+}
+
+/**
+ * Validate serialized state
+ */
+export function validateState(serialized: SerializedAgentState): {
+  valid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  if (!serialized.agent?.name) {
+    errors.push('Missing agent name');
+  }
+
+  if (!serialized.agent?.type) {
+    errors.push('Missing agent type');
+  }
+
+  if (!serialized.version) {
+    errors.push('Missing version');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/packaging/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Types for agent packaging
+ */
+
+/**
+ * Supported agent types that can be packaged
+ */
+export type AgentType = 'clawdbot' | 'goose' | 'cline' | 'generic';
+
+/**
+ * Agent configuration as detected from the source directory
+ */
+export interface AgentConfig {
+  /** Name of the agent */
+  name: string;
+  /** Detected agent type */
+  type: AgentType;
+  /** Source directory path */
+  sourcePath: string;
+  /** Entry point file (if detected) */
+  entryPoint?: string;
+  /** Agent version (if detected) */
+  version?: string;
+}
+
+/**
+ * Options for the packaging process
+ */
+export interface PackageOptions {
+  /** Source directory containing the agent */
+  sourcePath: string;
+  /** Output directory for compiled artifacts */
+  outputPath?: string;
+  /** Force overwrite of existing output files */
+  force?: boolean;
+  /** Skip validation steps */
+  skipValidation?: boolean;
+  /** Compilation target (wasmedge for local, motoko for ICP) */
+  target?: 'wasmedge' | 'motoko' | 'pure-wasm';
+  /** Enable debugging features (source maps, verbose output) */
+  debug?: boolean;
+  /** Optimization level (0-3) */
+  optimize?: number;
+
+  // ── ic-wasm optimization options ──────────────────────────────────────
+
+  /** Run ic-wasm optimize after WASM generation (requires ic-wasm) */
+  icWasmOptimize?: boolean;
+  /** Run ic-wasm shrink to remove unused functions (requires ic-wasm) */
+  icWasmShrink?: boolean;
+  /** Validate WASM against Candid .did interface (requires ic-wasm) */
+  candidInterface?: string;
+  /** Memory limit to set via ic-wasm resource (e.g. '4GiB') */
+  memoryLimit?: string;
+  /** Compute quota to set via ic-wasm resource */
+  computeQuota?: string;
+}
+
+/**
+ * Result of a successful packaging operation
+ */
+export interface PackageResult {
+  /** Detected agent configuration */
+  config: AgentConfig;
+  /** Path to the generated WASM file */
+  wasmPath: string;
+  /** Path to the generated WAT file (WebAssembly Text format) */
+  watPath: string;
+  /** Path to the serialized state JSON */
+  statePath: string;
+  /** Path to the generated JavaScript bundle */
+  jsBundlePath?: string;
+  /** Path to the generated source map (if enabled) */
+  sourceMapPath?: string;
+  /** Path to the generated manifest file */
+  manifestPath?: string;
+  /** Path to the generated Candid interface (if motoko target) */
+  didPath?: string;
+  /** Size of the WASM file in bytes */
+  wasmSize: number;
+  /** Compilation target used */
+  target: 'wasmedge' | 'motoko' | 'pure-wasm';
+  /** Timestamp of the packaging operation */
+  timestamp: Date;
+  /** Compilation duration in milliseconds */
+  duration?: number;
+  /** Number of functions exported */
+  functionCount?: number;
+
+  // ── ic-wasm optimization results ────────────────────────────────────
+
+  /** Original WASM size before ic-wasm optimization (bytes) */
+  originalWasmSize?: number;
+  /** Size reduction percentage from optimization (0-100) */
+  optimizationReductionPercent?: number;
+  /** Whether Candid validation passed */
+  candidValidationPassed?: boolean;
+  /** Optimization warnings */
+  optimizationWarnings?: string[];
+}
+
+/**
+ * Validation error that occurred during packaging
+ */
+export interface ValidationError {
+  /** Error code for programmatic handling */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** File path related to the error (if applicable) */
+  filePath?: string;
+}
+
+/**
+ * Result of agent validation
+ */
+export interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** List of validation errors (if any) */
+  errors: ValidationError[];
+  /** List of validation warnings */
+  warnings: string[];
+}
+
+/**
+ * Parsed agent configuration with agent-specific settings
+ */
+export interface ParsedAgentConfig {
+  base: {
+    name: string;
+    version?: string;
+    description?: string;
+  };
+  type: 'clawdbot' | 'goose' | 'cline' | 'generic';
+}
+
+/**
+ * Config file location
+ */
+export interface ConfigFilePath {
+  path: string;
+  type: 'json' | 'yaml' | 'directory';
+}