@memberjunction/ai-agent-manager 4.0.0 → 4.2.0

package/.turbo/turbo-build.log

@@ -1,6 +1,4 @@
-
-⠙
-> @memberjunction/ai-agent-manager@4.0.0 build
-> tsc && tsc-alias -f
-
-⠙⠙
+
+> @memberjunction/ai-agent-manager@4.2.0 build
+> tsc && tsc-alias -f
+

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @memberjunction/ai-agent-manager
 
+## 4.2.0
+
+### Patch Changes
+
+- @memberjunction/ai-agents@4.2.0
+- @memberjunction/ai-engine-base@4.2.0
+- @memberjunction/ai-core-plus@4.2.0
+- @memberjunction/aiengine@4.2.0
+- @memberjunction/core@4.2.0
+- @memberjunction/core-entities@4.2.0
+- @memberjunction/global@4.2.0
+- @memberjunction/templates@4.2.0
+
+## 4.1.0
+
+### Patch Changes
+
+- Updated dependencies [77839a9]
+- Updated dependencies [9fab8ca]
+- Updated dependencies [2ea241f]
+- Updated dependencies [5af036f]
+  - @memberjunction/core@4.1.0
+  - @memberjunction/templates@4.1.0
+  - @memberjunction/core-entities@4.1.0
+  - @memberjunction/ai-agents@4.1.0
+  - @memberjunction/ai-engine-base@4.1.0
+  - @memberjunction/ai-core-plus@4.1.0
+  - @memberjunction/aiengine@4.1.0
+  - @memberjunction/global@4.1.0
+
 ## 4.0.0
 
 ### Major Changes

package/README.md

@@ -0,0 +1,162 @@
+# @memberjunction/ai-agent-manager-core
+
+Core package for the MemberJunction Agent Manager system -- a multi-agent pipeline that designs, validates, and persists new AI agents from natural language descriptions. This package contains three specialized agents and the AgentSpecSync utility for database persistence.
+
+## Architecture
+
+```mermaid
+graph TD
+    A["PlanningDesignerAgent<br/>(Research + Design)"] -->|produces design| B["ArchitectAgent<br/>(Validate + Build Spec)"]
+    B -->|produces AgentSpec| C["BuilderAgent<br/>(Persist to DB)"]
+    C -->|uses| D["AgentSpecSync<br/>(Database Sync)"]
+    D -->|creates/updates| E["AI Agents + Prompts<br/>+ Actions + Steps<br/>+ Relationships"]
+
+    A -->|extends| F["BaseAgent<br/>(@memberjunction/ai-agents)"]
+    B -->|extends| F
+    C -->|extends| F
+
+    style A fill:#7c5295,stroke:#563a6b,color:#fff
+    style B fill:#7c5295,stroke:#563a6b,color:#fff
+    style C fill:#7c5295,stroke:#563a6b,color:#fff
+    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style E fill:#b8762f,stroke:#8a5722,color:#fff
+    style F fill:#2d6a9f,stroke:#1a4971,color:#fff
+```
+
+## Agent Pipeline
+
+```mermaid
+sequenceDiagram
+    participant User as User Request
+    participant PD as PlanningDesigner
+    participant AR as Architect
+    participant BU as Builder
+    participant DB as Database
+
+    User->>PD: "Create an agent that..."
+    PD->>PD: Research existing agents
+    PD->>PD: Research available actions
+    PD->>PD: Research database schema
+    PD->>PD: Produce TechnicalDesign
+    PD-->>AR: TechnicalDesign payload
+    AR->>AR: Transform to AgentSpec JSON
+    AR->>AR: Validate fields + references
+    AR->>AR: Auto-correct minor issues
+    AR-->>BU: Validated AgentSpec
+    BU->>BU: Create AgentSpecSync
+    BU->>DB: SaveToDatabase()
+    DB-->>BU: AgentSpecSyncResult
+    BU-->>User: Created agent ID + mutations
+```
+
+## Components
+
+### PlanningDesignerAgent
+
+Designs agent architectures by researching existing capabilities before producing a design. Overrides `validateSuccessNextStep` to enforce that required research actions are called before finalizing designs.
+
+Key responsibilities:
+- Force discovery of existing agents before selecting actions
+- Force discovery of available actions before designing
+- Force database schema research for CRUD operations
+- Prevent hallucination of non-existent entities or actions
+- Ensure designs are research-backed, not assumption-based
+
+### ArchitectAgent
+
+Transforms technical designs into validated AgentSpec JSON objects. Validates all references and auto-corrects minor issues before passing to the Builder.
+
+Key responsibilities:
+- Validate required fields (Name, TypeID, etc.)
+- Verify action IDs exist in the database
+- Verify prompt IDs exist if specified
+- Validate SubAgent structure
+- Auto-correct casing and missing optional fields
+- Force retry with detailed errors if validation fails
+
+### BuilderAgent
+
+A code-based agent (overrides `executeAgentInternal` to bypass chat loop) that persists validated AgentSpecs to the database. Runs once and returns success or failure.
+
+Key responsibilities:
+- Receive validated AgentSpec from payload
+- Create AgentSpecSync instance
+- Persist all related records to database
+- Track mutations in AI Agent Run Steps
+- Return created agent ID or detailed error
+
+### AgentSpecSync
+
+Utility class for synchronizing AgentSpec objects with the database. Handles creation, updates, and deletion of all related records with diff-based orphan cleanup.
+
+Key capabilities:
+- Creates/updates AI Agent records
+- Manages prompts and agent-prompt associations
+- Manages action associations
+- Manages sub-agent relationships via AI Agent Relationships
+- Manages agent steps and step paths
+- Performs topological sorting for dependency ordering
+- Returns detailed mutation log (`AgentSpecSyncMutation[]`)
+
+## Installation
+
+```bash
+npm install @memberjunction/ai-agent-manager-core
+```
+
+## Usage
+
+### Using AgentSpecSync Directly
+
+```typescript
+import { AgentSpecSync } from '@memberjunction/ai-agent-manager-core';
+import { AgentSpec } from '@memberjunction/ai-core-plus';
+
+const spec: AgentSpec = {
+    Name: 'My Custom Agent',
+    TypeID: 'type-uuid-here',
+    Description: 'An agent that processes customer feedback',
+    Actions: [
+        { ActionID: 'action-uuid-1' },
+        { ActionID: 'action-uuid-2' }
+    ],
+    SubAgents: []
+};
+
+const sync = new AgentSpecSync(spec, contextUser);
+sync.markDirty();
+
+const result = await sync.SaveToDatabase();
+
+if (result.success) {
+    console.log('Agent created with ID:', result.agentId);
+    for (const mutation of result.mutations) {
+        console.log(`${mutation.Operation} ${mutation.Entity}: ${mutation.Description}`);
+    }
+}
+```
+
+## Key Types
+
+| Type | Description |
+|------|-------------|
+| `AgentSpecSyncMutation` | Single database operation record (Entity, Operation, ID, Description) |
+| `AgentSpecSyncResult` | Result with agentId, success flag, and mutations array |
+
+## Class Registration
+
+| Agent | Registration Key |
+|-------|-----------------|
+| PlanningDesignerAgent | `@RegisterClass(BaseAgent, 'AgentPlanningDesigner')` |
+| AgentArchitectAgent | `@RegisterClass(BaseAgent, 'AgentArchitectAgent')` |
+| AgentBuilderAgent | `@RegisterClass(BaseAgent, 'AgentBuilderAgent')` |
+
+## Dependencies
+
+- `@memberjunction/ai-agents` - BaseAgent, PayloadManager
+- `@memberjunction/ai-core-plus` - AgentSpec, ExecuteAgentParams, extended entity types
+- `@memberjunction/aiengine` - AIEngine for model resolution
+- `@memberjunction/core` - Metadata, RunView, entity operations
+- `@memberjunction/core-entities` - AI Agent, Step, Action, Relationship entities
+- `@memberjunction/global` - Class registration via @RegisterClass
+- `@memberjunction/templates` - TemplateEngineServer for prompt rendering

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-agent-manager",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Core interfaces and types for the MemberJunction Agent Manager system",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,14 +20,14 @@
   "author": "MemberJunction",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/ai-agents": "4.0.0",
-    "@memberjunction/ai-core-plus": "4.0.0",
-    "@memberjunction/ai-engine-base": "4.0.0",
-    "@memberjunction/aiengine": "4.0.0",
-    "@memberjunction/core": "4.0.0",
-    "@memberjunction/core-entities": "4.0.0",
-    "@memberjunction/global": "4.0.0",
-    "@memberjunction/templates": "4.0.0"
+    "@memberjunction/ai-agents": "4.2.0",
+    "@memberjunction/ai-core-plus": "4.2.0",
+    "@memberjunction/ai-engine-base": "4.2.0",
+    "@memberjunction/aiengine": "4.2.0",
+    "@memberjunction/core": "4.2.0",
+    "@memberjunction/core-entities": "4.2.0",
+    "@memberjunction/global": "4.2.0",
+    "@memberjunction/templates": "4.2.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.11",

package/dist/interfaces/agent-definition.interface.d.ts

@@ -1,158 +0,0 @@
-/**
- * Agent Definition Interface for MemberJunction Agent Manager
- *
- * This interface defines the complete structure for AI agents at any level
- * of hierarchy. All text fields support markdown formatting for rich documentation.
- *
- * @module @memberjunction/agent-manager-core
- */
-/**
- * Complete agent definition that supports n-levels of sub-agent hierarchy
- * All text fields support markdown formatting for rich documentation
- */
-export interface AIAgentDefinition {
-    name: string;
-    description: string;
-    readonly type: 'Loop';
-    purpose: string;
-    actions: {
-        /** Action ID from the system action library */
-        id: string;
-        /** Human-readable name of the action */
-        name: string;
-        /** Justification for why this action is needed */
-        reason: string;
-    }[];
-    prompt: {
-        /** System prompt for this agent */
-        systemPrompt?: string;
-        /** Template variables documentation */
-        templateVariables?: string;
-        /** Prompt analysis and notes */
-        promptNotes?: string;
-    };
-    payloadDownstreamPaths?: string[];
-    payloadUpstreamPaths?: string[];
-    subAgents?: AIAgentDefinition[];
-    executionOrder?: number;
-    exposeAsAction?: boolean;
-    iconClass?: string;
-    finalPayloadValidation?: string;
-    finalPayloadValidationMode?: 'Retry' | 'Fail' | 'Warn';
-    finalPayloadValidationMaxRetries?: number;
-}
-/**
- * Root context for the Agent Manager that tracks the entire creation process
- */
-export interface AIAgentManagerContext {
-    agent: AIAgentDefinition;
-    processStage: 'requirements' | 'design' | 'prompting' | 'implementation' | 'validation' | 'complete';
-    session: {
-        id: string;
-        startedAt: string;
-        userId: string;
-        userName: string;
-        purpose: string;
-        notes: string;
-    };
-    validation?: {
-        isValid: boolean;
-        report: string;
-    };
-}
-/**
- * Agent Manager Payload Definition
- * This type defines the structure for data passed between Agent Manager sub-agents
- */
-export interface AgentManagerPayload {
-    /**
-     * Metadata about the agent creation process
-     */
-    metadata: {
-        /** Unique identifier for this agent creation session */
-        sessionId: string;
-        /** Current status of the agent creation process */
-        status: 'requirements' | 'design' | 'prompting' | 'implementation' | 'validation' | 'complete';
-        /** Original user request for agent creation */
-        originalRequest: string;
-        /** The agent who last modified the payload */
-        lastModifiedBy: string;
-    };
-    /**
-     * Requirements Analyst agent section
-     */
-    requirements?: {
-        /** High-level business objective this agent will serve */
-        businessGoal: string;
-        /** Specific functional capabilities the agent must have */
-        functionalRequirements: string;
-        /** Technical constraints and requirements */
-        technicalRequirements: string;
-        /** Data sources and data handling requirements */
-        dataRequirements: string;
-        /** System integration requirements */
-        integrationRequirements: string;
-        /** Key assumptions made during requirements gathering */
-        assumptions: string;
-        /** Identified risks and mitigation strategies */
-        risks: string;
-        /** Explicitly defined scope boundaries */
-        outOfScope: string;
-        /** Measurable criteria for success */
-        successCriteria: string;
-    };
-    /**
-     * Planning Designer agent section
-     */
-    design?: {
-        /** Complete agent hierarchy structure */
-        agentHierarchy: AIAgentDefinition;
-        /** Architecture documentation */
-        architecture: {
-            /** How agents will execute in sequence/parallel */
-            executionFlow: string;
-            /** How data flows between agents */
-            dataFlow: string;
-            /** Error handling and recovery strategies */
-            errorHandling: string;
-        };
-    };
-    /**
-     * Prompt Designer agent section
-     */
-    prompts?: {
-        /** Map of agent names to their prompt configurations */
-        [agentName: string]: {
-            /** Complete system prompt for the agent */
-            systemPrompt: string;
-            /** Documentation of template variables used */
-            templateVariables: string;
-            /** Analysis and optimization notes */
-            promptNotes: string;
-        };
-    };
-    /**
-     * Agent Manager implementation section
-     */
-    implementation?: {
-        /** Agents that have been created in the system */
-        createdAgents: {
-            /** Database ID of the created agent */
-            id: string;
-            /** Name of the agent */
-            name: string;
-            /** Current status of the agent */
-            status: 'created' | 'configured' | 'validated' | 'active';
-        }[];
-        /** Validation results for the created agent system */
-        validationResults: {
-            /** ID of the agent that was validated */
-            agentId: string;
-            /** Whether the agent passed validation */
-            isValid: boolean;
-            /** Any issues found during validation */
-            issues: string[];
-        }[];
-    };
-}
-//# sourceMappingURL=agent-definition.interface.d.ts.map

package/dist/interfaces/agent-definition.interface.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-definition.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/agent-definition.interface.ts"],"names":[],"mappings":"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"}

package/dist/interfaces/agent-definition.interface.js

@@ -1,11 +0,0 @@
-"use strict";
-/**
- * Agent Definition Interface for MemberJunction Agent Manager
- *
- * This interface defines the complete structure for AI agents at any level
- * of hierarchy. All text fields support markdown formatting for rich documentation.
- *
- * @module @memberjunction/agent-manager-core
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=agent-definition.interface.js.map

package/dist/interfaces/agent-definition.interface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-definition.interface.js","sourceRoot":"","sources":["../../src/interfaces/agent-definition.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}