@defai.digital/agent-domain 13.0.3

package/src/index.ts

@@ -0,0 +1,172 @@
+/**
+ * @defai.digital/agent-domain
+ *
+ * Agent profiles and orchestration for AutomatosX.
+ * Manages specialized AI agents with defined workflows, personalities,
+ * abilities, and orchestration rules.
+ */
+
+// Types
+export type {
+  AgentRegistry,
+  AgentFilter,
+  AgentExecutor,
+  ExecutionStatus,
+  ExecutionProgress,
+  DelegationRequest,
+  DelegationManager,
+  AgentEventHandler,
+  AgentEventEmitter,
+  StepExecutorFn,
+  StepExecutionContext,
+  StepExecutionResult,
+  AgentDomainConfig,
+  // Prompt executor types
+  PromptExecutor,
+  PromptExecutionRequest,
+  PromptExecutionResponse,
+  PromptStepConfig,
+  // Tool executor types (INV-TOOL-001, INV-TOOL-002, INV-TOOL-003)
+  ToolExecutor,
+  // Loader types
+  AgentLoader,
+  AgentLoaderConfig,
+  // Selector types
+  AgentSelector,
+  AgentSelectionResult,
+  AgentSelectionContext,
+  // Ability integration types
+  AbilityManagerLike,
+  // Delegation tracker port types (DI pattern)
+  DelegationTrackerPort,
+  DelegationTrackerFactory,
+  // Checkpoint port types (DI pattern)
+  CheckpointStoragePort,
+  CheckpointManagerPort,
+  Checkpoint,
+  CheckpointStorageFactory,
+  CheckpointManagerFactory,
+  // Parallel executor port types (DI pattern)
+  ParallelExecutorPort,
+  ParallelStepExecutor,
+  ParallelStepResult,
+  ParallelGroupResult,
+  ParallelExecutorFactory,
+} from './types.js';
+
+export { DEFAULT_AGENT_DOMAIN_CONFIG } from './types.js';
+
+// Registry
+export {
+  InMemoryAgentRegistry,
+  AgentRegistryError,
+  createAgentRegistry,
+} from './registry.js';
+
+// Persistent Registry
+export {
+  PersistentAgentRegistry,
+  createPersistentAgentRegistry,
+  getDefaultAgentStoragePath,
+  type PersistentRegistryConfig,
+} from './persistent-registry.js';
+
+// Executor
+export { DefaultAgentExecutor, createAgentExecutor } from './executor.js';
+
+// Enhanced Executor (full feature support)
+export {
+  EnhancedAgentExecutor,
+  createEnhancedAgentExecutor,
+  type EnhancedAgentDomainConfig,
+} from './enhanced-executor.js';
+
+// Prompt Executor
+export {
+  StubPromptExecutor,
+  ProviderPromptExecutor,
+  createStubPromptExecutor,
+  createProviderPromptExecutor,
+  type ProviderPromptExecutorConfig,
+  type ProviderRegistryLike,
+  type ProviderLike,
+} from './prompt-executor.js';
+
+// Loader
+export { FileSystemAgentLoader, createAgentLoader } from './loader.js';
+
+// Selector
+export { KeywordAgentSelector, createAgentSelector } from './selector.js';
+
+// Selection Service (INV-AGT-SEL-001 to INV-AGT-SEL-006)
+export {
+  AgentSelectionService,
+  createAgentSelectionService,
+  type AgentSelectionServicePort,
+} from './selection-service.js';
+
+// Workflow Templates
+export {
+  WORKFLOW_TEMPLATES,
+  PROMPT_RESPONSE_TEMPLATE,
+  RESEARCH_TEMPLATE,
+  CODE_REVIEW_TEMPLATE,
+  MULTI_STEP_TEMPLATE,
+  DELEGATE_CHAIN_TEMPLATE,
+  AGENT_SELECTION_TEMPLATE,
+  getWorkflowTemplate,
+  getAvailableTemplates,
+  createWorkflowFromTemplate,
+  isValidTemplateName,
+  getTemplateDescription,
+  type WorkflowTemplateName,
+  type WorkflowTemplate,
+} from './workflow-templates.js';
+
+// Stub factories (for DI fallbacks)
+export { stubDelegationTrackerFactory, resetStubWarning as resetDelegationStubWarning } from './stub-delegation-tracker.js';
+export { stubCheckpointStorageFactory, stubCheckpointManagerFactory, resetCheckpointStubWarning } from './stub-checkpoint.js';
+export { stubParallelExecutorFactory, resetParallelStubWarning } from './stub-parallel-executor.js';
+
+// Production factories (real implementations for wiring)
+export {
+  createCheckpointStorageFactory,
+  createCheckpointManagerFactory,
+  createDelegationTrackerFactory,
+  createParallelExecutorFactory,
+  createProductionFactories,
+  type ProductionFactoriesConfig,
+  type ProductionFactories,
+} from './production-factories.js';
+
+// Re-export contract types for convenience
+export type {
+  AgentProfile,
+  AgentRunOptions,
+  AgentResult,
+  AgentError,
+  AgentEvent,
+  AgentEventType,
+  AgentEventPayload,
+  AgentWorkflowStep,
+  AgentStepType,
+  AgentRetryPolicy,
+  AgentPersonality,
+  AbilitySelection,
+  OrchestrationConfig,
+  SelectionMetadata,
+  RedirectRule,
+} from '@defai.digital/contracts';
+
+export {
+  AgentProfileSchema,
+  AgentRunOptionsSchema,
+  AgentResultSchema,
+  AgentErrorSchema,
+  AgentEventSchema,
+  AgentWorkflowStepSchema,
+  AgentErrorCode,
+  validateAgentProfile,
+  safeValidateAgentProfile,
+  validateAgentRunOptions,
+} from '@defai.digital/contracts';

package/src/loader.ts

@@ -0,0 +1,191 @@
+/**
+ * Agent Profile Loader
+ *
+ * Loads agent profiles from YAML/JSON files.
+ *
+ * Invariants:
+ * - INV-AGT-LDR-001: All loaded profiles must pass schema validation
+ * - INV-AGT-LDR-002: File extensions must match configured extensions
+ * - INV-AGT-LDR-003: Agent IDs must be unique across all loaded profiles
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { validateAgentProfile, type AgentProfile } from '@defai.digital/contracts';
+import type { AgentLoader, AgentLoaderConfig } from './types.js';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_EXTENSIONS = ['.yaml', '.yml', '.json'];
+
+// ============================================================================
+// File System Agent Loader
+// ============================================================================
+
+/**
+ * Loads agent profiles from the file system
+ */
+export class FileSystemAgentLoader implements AgentLoader {
+  private readonly config: Required<AgentLoaderConfig>;
+  private cache = new Map<string, AgentProfile>();
+  private loaded = false;
+
+  constructor(config: AgentLoaderConfig) {
+    this.config = {
+      agentsDir: config.agentsDir,
+      extensions: config.extensions ?? DEFAULT_EXTENSIONS,
+      watch: config.watch ?? false,
+    };
+  }
+
+  /**
+   * Load an agent profile by ID
+   */
+  async load(agentId: string): Promise<AgentProfile | undefined> {
+    if (!this.loaded) {
+      await this.loadAll();
+    }
+    return this.cache.get(agentId);
+  }
+
+  /**
+   * Load all agent profiles from the directory
+   */
+  async loadAll(): Promise<AgentProfile[]> {
+    this.cache.clear();
+
+    const dirPath = this.config.agentsDir;
+
+    // Check if directory exists
+    if (!fs.existsSync(dirPath)) {
+      this.loaded = true;
+      return [];
+    }
+
+    const files = fs.readdirSync(dirPath);
+    const profiles: AgentProfile[] = [];
+
+    for (const file of files) {
+      const ext = path.extname(file).toLowerCase();
+      if (!this.config.extensions.includes(ext)) {
+        continue;
+      }
+
+      const filePath = path.join(dirPath, file);
+      const profile = await this.loadFile(filePath);
+
+      if (profile) {
+        // INV-AGT-LDR-003: Check for duplicate agent IDs
+        if (this.cache.has(profile.agentId)) {
+          console.warn(
+            `Duplicate agent ID "${profile.agentId}" found in ${file}, skipping`
+          );
+          continue;
+        }
+
+        this.cache.set(profile.agentId, profile);
+        profiles.push(profile);
+      }
+    }
+
+    this.loaded = true;
+    return profiles;
+  }
+
+  /**
+   * Check if an agent exists
+   */
+  async exists(agentId: string): Promise<boolean> {
+    if (!this.loaded) {
+      await this.loadAll();
+    }
+    return this.cache.has(agentId);
+  }
+
+  /**
+   * Reload all agent profiles
+   */
+  async reload(): Promise<void> {
+    this.loaded = false;
+    await this.loadAll();
+  }
+
+  /**
+   * Load a single agent profile from a file
+   */
+  private async loadFile(filePath: string): Promise<AgentProfile | undefined> {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const ext = path.extname(filePath).toLowerCase();
+
+      let data: unknown;
+      if (ext === '.json') {
+        data = JSON.parse(content);
+      } else {
+        data = parseYaml(content);
+      }
+
+      // Transform YAML fields to match schema
+      const transformed = this.transformYamlToProfile(data);
+
+      // INV-AGT-LDR-001: Validate against schema
+      const profile = validateAgentProfile(transformed);
+      return profile;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      console.warn(`Failed to load agent from ${filePath}: ${message}`);
+      return undefined;
+    }
+  }
+
+  /**
+   * Transform YAML format to AgentProfile format
+   */
+  private transformYamlToProfile(data: unknown): unknown {
+    if (typeof data !== 'object' || data === null) {
+      return data;
+    }
+
+    const yaml = data as Record<string, unknown>;
+
+    // Map YAML 'name' to 'agentId'
+    const profile: Record<string, unknown> = {
+      ...yaml,
+      agentId: yaml.name ?? yaml.agentId,
+    };
+
+    // Map 'abilities' array to 'abilities.core' if it's an array
+    if (Array.isArray(yaml.abilities)) {
+      profile.abilities = {
+        core: yaml.abilities,
+        taskBased: (yaml.abilitySelection as Record<string, unknown>)?.taskBased,
+      };
+    }
+
+    // Map 'role' to description if description is missing
+    if (!yaml.description && yaml.role) {
+      profile.description = yaml.role as string;
+    }
+
+    // Remove YAML-specific fields
+    delete profile.name;
+    delete profile.abilitySelection;
+    delete profile.cognitiveFramework;
+
+    return profile;
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Creates a file system agent loader
+ */
+export function createAgentLoader(config: AgentLoaderConfig): AgentLoader {
+  return new FileSystemAgentLoader(config);
+}

package/src/persistent-registry.ts

@@ -0,0 +1,235 @@
+/**
+ * Persistent Agent Registry
+ *
+ * Wraps the in-memory registry with file-based persistence.
+ * Agents are saved to a JSON file and loaded on startup.
+ *
+ * Invariants:
+ * - INV-AGT-PERSIST-001: All changes are persisted to disk
+ * - INV-AGT-PERSIST-002: Registry loads existing agents on initialization
+ * - INV-AGT-PERSIST-003: File operations are atomic (write to temp, then rename)
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  validateAgentProfile,
+  type AgentProfile,
+  DATA_DIR_NAME,
+  AGENTS_FILENAME,
+  DEFAULT_SCHEMA_VERSION,
+} from '@defai.digital/contracts';
+import { InMemoryAgentRegistry } from './registry.js';
+import type { AgentRegistry, AgentFilter } from './types.js';
+
+/**
+ * Configuration for persistent registry
+ */
+export interface PersistentRegistryConfig {
+  /**
+   * Path to the JSON file for storing agents
+   */
+  storagePath: string;
+
+  /**
+   * Whether to create the directory if it doesn't exist
+   */
+  createDir?: boolean;
+
+  /**
+   * Whether to load existing agents on initialization
+   */
+  loadOnInit?: boolean;
+}
+
+/**
+ * Persistent agent registry that saves to JSON file
+ */
+export class PersistentAgentRegistry implements AgentRegistry {
+  private readonly inMemory: InMemoryAgentRegistry;
+  private readonly config: Required<PersistentRegistryConfig>;
+  private initialized = false;
+
+  constructor(config: PersistentRegistryConfig) {
+    this.inMemory = new InMemoryAgentRegistry();
+    this.config = {
+      storagePath: config.storagePath,
+      createDir: config.createDir ?? true,
+      loadOnInit: config.loadOnInit ?? true,
+    };
+  }
+
+  /**
+   * Initialize the registry (load from disk if configured)
+   */
+  private async ensureInitialized(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    if (this.config.loadOnInit) {
+      await this.loadFromDisk();
+    }
+
+    this.initialized = true;
+  }
+
+  /**
+   * Register a new agent profile
+   * INV-AGT-PERSIST-001: Persists to disk after registration
+   */
+  async register(profile: AgentProfile): Promise<void> {
+    await this.ensureInitialized();
+    await this.inMemory.register(profile);
+    await this.saveToDisk();
+  }
+
+  /**
+   * Get an agent by ID
+   */
+  async get(agentId: string): Promise<AgentProfile | undefined> {
+    await this.ensureInitialized();
+    return this.inMemory.get(agentId);
+  }
+
+  /**
+   * List all registered agents with optional filtering
+   */
+  async list(filter?: AgentFilter): Promise<AgentProfile[]> {
+    await this.ensureInitialized();
+    return this.inMemory.list(filter);
+  }
+
+  /**
+   * Update an agent profile
+   * INV-AGT-PERSIST-001: Persists to disk after update
+   */
+  async update(agentId: string, updates: Partial<AgentProfile>): Promise<void> {
+    await this.ensureInitialized();
+    await this.inMemory.update(agentId, updates);
+    await this.saveToDisk();
+  }
+
+  /**
+   * Remove an agent
+   * INV-AGT-PERSIST-001: Persists to disk after removal
+   */
+  async remove(agentId: string): Promise<void> {
+    await this.ensureInitialized();
+    await this.inMemory.remove(agentId);
+    await this.saveToDisk();
+  }
+
+  /**
+   * Check if an agent exists
+   */
+  async exists(agentId: string): Promise<boolean> {
+    await this.ensureInitialized();
+    return this.inMemory.exists(agentId);
+  }
+
+  /**
+   * Load agents from disk
+   * INV-AGT-PERSIST-002: Called on initialization
+   */
+  private async loadFromDisk(): Promise<void> {
+    const filePath = this.config.storagePath;
+
+    if (!fs.existsSync(filePath)) {
+      return;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const data = JSON.parse(content);
+
+      if (!Array.isArray(data.agents)) {
+        console.warn(`Invalid agents file format at ${filePath}`);
+        return;
+      }
+
+      for (const agentData of data.agents) {
+        try {
+          const profile = validateAgentProfile(agentData);
+          // Use internal method to avoid triggering save
+          await this.inMemory.register(profile);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : 'Unknown error';
+          console.warn(`Failed to load agent "${agentData.agentId}": ${message}`);
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      console.warn(`Failed to load agents from ${filePath}: ${message}`);
+    }
+  }
+
+  /**
+   * Save agents to disk
+   * INV-AGT-PERSIST-003: Atomic write using temp file + rename
+   */
+  private async saveToDisk(): Promise<void> {
+    const filePath = this.config.storagePath;
+    const dirPath = path.dirname(filePath);
+
+    // Create directory if needed
+    if (this.config.createDir && !fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+
+    // Get all agents
+    const agents = await this.inMemory.list();
+
+    // Create data structure
+    const data = {
+      version: DEFAULT_SCHEMA_VERSION,
+      updatedAt: new Date().toISOString(),
+      agents,
+    };
+
+    // INV-AGT-PERSIST-003: Write to temp file first, then rename
+    const tempPath = `${filePath}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(data, null, 2), 'utf-8');
+    fs.renameSync(tempPath, filePath);
+  }
+
+  /**
+   * Get the number of registered agents
+   */
+  get size(): number {
+    return this.inMemory.size;
+  }
+
+  /**
+   * Force reload from disk
+   */
+  async reload(): Promise<void> {
+    this.inMemory.clear();
+    this.initialized = false;
+    await this.ensureInitialized();
+  }
+}
+
+/**
+ * Creates a persistent agent registry
+ *
+ * @example
+ * ```typescript
+ * const registry = createPersistentAgentRegistry({
+ *   storagePath: getDefaultAgentStoragePath(),
+ * });
+ * ```
+ */
+export function createPersistentAgentRegistry(
+  config: PersistentRegistryConfig
+): AgentRegistry {
+  return new PersistentAgentRegistry(config);
+}
+
+/**
+ * Gets the default storage path for agents
+ * Uses DATA_DIR_NAME/AGENTS_FILENAME in current working directory
+ */
+export function getDefaultAgentStoragePath(): string {
+  return path.join(process.cwd(), DATA_DIR_NAME, AGENTS_FILENAME);
+}