@memberjunction/ai-agent-manager 2.106.0 → 2.108.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @memberjunction/ai-agent-manager@2.106.0 build
+> @memberjunction/ai-agent-manager@2.108.0 build
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @memberjunction/ai-agent-manager
 
+## 2.108.0
+
+### Minor Changes
+
+- d205a6c: migration
+
+### Patch Changes
+
+- Updated dependencies [d205a6c]
+- Updated dependencies [656d86c]
+  - @memberjunction/ai-core-plus@2.108.0
+  - @memberjunction/core-entities@2.108.0
+  - @memberjunction/core@2.108.0
+  - @memberjunction/global@2.108.0
+
+## 2.107.0
+
 ## 2.106.0
 
 ## 2.105.0

package/dist/agent-spec-sync.d.ts

@@ -0,0 +1,355 @@
+import { UserInfo } from '@memberjunction/core';
+import { AgentSpec } from '@memberjunction/ai-core-plus';
+/**
+ * AgentSpecSync provides a high-level interface for working with AI Agent metadata in MemberJunction.
+ *
+ * This class serves as a bi-directional bridge between the simple, serializable {@link AgentSpec}
+ * format and the complex MemberJunction database metadata across three core entities:
+ * - {@link AIAgentEntity} - Core agent configuration
+ * - {@link AIAgentActionEntity} - Agent-action relationships
+ * - {@link AIAgentRelationshipEntity} - Parent-child agent relationships
+ *
+ * ## Key Features
+ *
+ * - **Load from Database**: Load complete agent hierarchies including all sub-agents and actions
+ * - **Save to Database**: Persist changes atomically with full validation
+ * - **Recursive Support**: Handles n-level agent hierarchies automatically
+ * - **Type Safety**: Full TypeScript typing with proper entity types
+ * - **Dirty Tracking**: Knows when changes need to be saved
+ * - **JSON Serialization**: Easy export for APIs and storage
+ *
+ * ## Usage Examples
+ *
+ * ### Load an existing agent
+ * ```typescript
+ * const spec = await AgentSpecSync.LoadFromDatabase('agent-uuid', contextUser);
+ * console.log('Agent Name:', spec.spec.Name);
+ * console.log('Actions:', spec.spec.Actions?.length);
+ * ```
+ *
+ * ### Create a new agent
+ * ```typescript
+ * const newAgent = new AgentSpecSync({
+ *     Name: 'My New Agent',
+ *     Description: 'Does amazing things',
+ *     IconClass: 'fa-robot',
+ *     InvocationMode: 'Any'
+ * }, contextUser);
+ *
+ * const agentId = await newAgent.SaveToDatabase();
+ * ```
+ *
+ * ### Modify and save
+ * ```typescript
+ * const spec = await AgentSpecSync.LoadFromDatabase('agent-uuid', contextUser);
+ * spec.spec.Description = 'Updated description';
+ * spec.spec.MaxCostPerRun = 10.00;
+ * spec.markDirty();
+ * await spec.SaveToDatabase();
+ * ```
+ *
+ * @module @memberjunction/ai-agent-manager
+ */
+export declare class AgentSpecSync {
+    /**
+     * The raw specification data structure containing all agent configuration
+     */
+    spec: AgentSpec;
+    /**
+     * Tracks whether this spec has been loaded from the database
+     * @private
+     */
+    private _isLoaded;
+    /**
+     * Tracks whether this spec has unsaved changes
+     * @private
+     */
+    private _isDirty;
+    /**
+     * Context user for database operations (required for server-side operations)
+     * @private
+     */
+    private _contextUser?;
+    /**
+     * Create a new AgentSpecSync instance.
+     *
+     * Note: This constructor is typically not called directly. Instead, use the static factory methods:
+     * - {@link LoadFromDatabase} - Load existing agent from database
+     * - {@link LoadByName} - Load agent by name
+     * - {@link FromRawSpec} - Create from raw spec data
+     *
+     * @param spec - Optional initial spec data (for creating new agents or working with existing data)
+     * @param contextUser - Optional context user (required for server-side operations)
+     */
+    constructor(spec?: Partial<AgentSpec>, contextUser?: UserInfo);
+    /**
+     * Load an agent and its complete hierarchy from the database by ID.
+     *
+     * This method efficiently loads the agent along with all its actions and sub-agents
+     * using batched queries to minimize database round trips. When `includeSubAgents` is true,
+     * it recursively loads the entire agent hierarchy.
+     *
+     * @param agentId - The unique ID of the agent to load
+     * @param contextUser - Optional context user (required for server-side operations)
+     * @param includeSubAgents - Whether to recursively load all sub-agents (default: true)
+     * @returns Promise resolving to AgentSpecSync instance with loaded data
+     * @throws {Error} If agent with specified ID is not found
+     *
+     * @example
+     * ```typescript
+     * // Load agent with all sub-agents
+     * const spec = await AgentSpecSync.LoadFromDatabase(
+     *     'agent-uuid-here',
+     *     contextUser,
+     *     true
+     * );
+     * ```
+     */
+    static LoadFromDatabase(agentId: string, contextUser?: UserInfo, includeSubAgents?: boolean): Promise<AgentSpecSync>;
+    /**
+     * Load an agent by name (must be unique).
+     *
+     * Searches for an agent with the specified name and loads it. If multiple agents
+     * have the same name, an error is thrown. Agent names should be unique within
+     * the system for this method to work reliably.
+     *
+     * @param agentName - The name of the agent to load
+     * @param contextUser - Optional context user (required for server-side operations)
+     * @param includeSubAgents - Whether to recursively load sub-agents (default: true)
+     * @returns Promise resolving to AgentSpecSync instance with loaded data
+     * @throws {Error} If agent is not found or multiple agents have the same name
+     *
+     * @example
+     * ```typescript
+     * const spec = await AgentSpecSync.LoadByName('My Agent', contextUser);
+     * ```
+     */
+    static LoadByName(agentName: string, contextUser?: UserInfo, includeSubAgents?: boolean): Promise<AgentSpecSync>;
+    /**
+     * Create a new agent spec from a raw specification.
+     *
+     * This creates an in-memory AgentSpecSync instance from raw data. The agent is not
+     * saved to the database until {@link SaveToDatabase} is called.
+     *
+     * @param rawSpec - The raw spec data conforming to {@link AgentSpec} interface
+     * @param contextUser - Optional context user (required when saving server-side)
+     * @returns New AgentSpecSync instance (not yet saved to database)
+     *
+     * @example
+     * ```typescript
+     * const rawSpec: AgentSpec = {
+     *     ID: '',
+     *     Name: 'New Agent',
+     *     Description: 'Agent description',
+     *     InvocationMode: 'Any',
+     *     Actions: [],
+     *     SubAgents: []
+     * };
+     * const spec = AgentSpecSync.FromRawSpec(rawSpec, contextUser);
+     * await spec.SaveToDatabase();
+     * ```
+     */
+    static FromRawSpec(rawSpec: AgentSpec, contextUser?: UserInfo): AgentSpecSync;
+    /**
+     * Load the complete agent specification from database entities.
+     *
+     * This method orchestrates loading from AIAgent, AIAgentAction, and AIAgentRelationship tables
+     * using batched queries for optimal performance. It handles both child agents (ParentID-based)
+     * and related agents (relationship-based).
+     *
+     * @private
+     * @param agentId - The agent ID to load
+     * @param includeSubAgents - Whether to recursively load sub-agents
+     * @throws {Error} If agent is not found
+     */
+    private loadFromEntities;
+    /**
+     * Map database entities to AgentSpec format.
+     *
+     * Transforms the normalized database entities into a single denormalized specification
+     * object that's easy to work with in code. Handles JSON parsing for all structured fields.
+     *
+     * @private
+     * @param agent - The main agent entity
+     * @param actions - Array of agent action entities
+     * @param childAgents - Array of child agent entities (ParentID-based)
+     * @param relatedAgents - Array of related agent relationship entities
+     * @returns Fully populated AgentSpec object
+     */
+    private mapEntitiesToRawSpec;
+    /**
+     * Map AIAgentActionEntity to AgentActionSpec format.
+     *
+     * @private
+     * @param action - The agent action entity from the database
+     * @returns Mapped action spec
+     */
+    private mapActionEntityToSpec;
+    /**
+     * Map child agent (ParentID-based) to SubAgentSpec format.
+     *
+     * @private
+     * @param childAgent - The child agent entity
+     * @returns Mapped sub-agent spec
+     */
+    private mapChildAgentToSpec;
+    /**
+     * Map related agent (relationship-based) to SubAgentSpec format.
+     *
+     * @private
+     * @param relationship - The agent relationship entity
+     * @returns Mapped sub-agent spec
+     */
+    private mapRelatedAgentToSpec;
+    /**
+     * Save the current spec to the database.
+     *
+     * This will create new records or update existing ones based on whether IDs exist.
+     * The save operation is performed atomically - if any part fails, no changes are committed.
+     *
+     * Validation is performed before saving. All entity-level validations defined in the
+     * database schema are executed, and any failures will prevent the save.
+     *
+     * @param validate - Whether to validate before saving (default: true)
+     * @returns Promise resolving to the saved agent ID
+     * @throws {Error} If validation fails or save operation fails
+     *
+     * @example
+     * ```typescript
+     * const spec = new AgentSpecSync({
+     *     Name: 'New Agent',
+     *     InvocationMode: 'Any'
+     * }, contextUser);
+     *
+     * const agentId = await spec.SaveToDatabase();
+     * console.log('Saved with ID:', agentId);
+     * ```
+     */
+    SaveToDatabase(validate?: boolean): Promise<string>;
+    /**
+     * Save the main AIAgent entity.
+     *
+     * @private
+     * @param validate - Whether to perform validation before saving
+     * @returns Promise resolving to the saved agent ID
+     * @throws {Error} If validation fails or save fails
+     */
+    private saveAgentEntity;
+    /**
+     * Save all actions for this agent.
+     *
+     * Creates or updates agent action records. Existing actions are updated, new actions
+     * are created. This method does not delete actions that are no longer in the spec -
+     * use a separate delete method for that.
+     *
+     * @private
+     * @param agentId - The parent agent ID
+     * @throws {Error} If any action save fails
+     */
+    private saveActions;
+    /**
+     * Save all sub-agents (both child and related types).
+     *
+     * Handles both ParentID-based child agents and relationship-based related agents.
+     * For child agents, updates the ParentID on the sub-agent entity. For related agents,
+     * creates or updates the relationship record.
+     *
+     * @private
+     * @param agentId - The parent agent ID
+     * @throws {Error} If any sub-agent save fails
+     */
+    private saveSubAgents;
+    /**
+     * Save a child sub-agent (ParentID-based relationship).
+     *
+     * For child agents, the relationship is established by setting the ParentID field
+     * on the child agent entity. If the SubAgentID is empty, this indicates a new
+     * child agent that needs to be created.
+     *
+     * @private
+     * @param parentId - The parent agent ID
+     * @param SubAgentSpec - The sub-agent specification
+     * @throws {Error} If child agent doesn't exist or save fails
+     */
+    private saveChildSubAgent;
+    /**
+     * Save a related sub-agent (relationship-based).
+     *
+     * Creates or updates an AIAgentRelationship record that links the parent and
+     * sub-agent. This includes the input/output mapping and context path configurations.
+     *
+     * @private
+     * @param agentId - The parent agent ID
+     * @param SubAgentSpec - The sub-agent specification
+     * @throws {Error} If relationship save fails
+     */
+    private saveRelatedSubAgent;
+    /**
+     * Parse a JSON string field, returning undefined if null/empty.
+     *
+     * Safely parses JSON fields from the database, handling null/undefined values
+     * and logging errors if parsing fails.
+     *
+     * @private
+     * @param jsonString - The JSON string to parse
+     * @returns Parsed object or undefined if null/empty/invalid
+     */
+    private parseJsonField;
+    /**
+     * Initialize a spec with defaults for any missing required fields.
+     *
+     * Takes a partial spec and fills in defaults for any missing fields to ensure
+     * a valid AgentSpec structure.
+     *
+     * @private
+     * @param partial - Partial agent specification
+     * @returns Complete AgentSpec with defaults
+     */
+    private initializeSpec;
+    /**
+     * Get a clean serializable version of the spec.
+     *
+     * Returns a plain JavaScript object suitable for JSON serialization,
+     * API responses, or storage. This is useful when you need to send the
+     * agent spec over the wire or store it in a file.
+     *
+     * @returns Clean copy of the agent specification
+     *
+     * @example
+     * ```typescript
+     * const spec = await AgentSpecSync.LoadFromDatabase('agent-uuid', contextUser);
+     * const json = spec.toJSON();
+     * res.json(json); // Send as API response
+     * ```
+     */
+    toJSON(): AgentSpec;
+    /**
+     * Check if this spec has unsaved changes.
+     *
+     * @returns True if there are unsaved changes, false otherwise
+     */
+    get isDirty(): boolean;
+    /**
+     * Check if this spec has been loaded from the database.
+     *
+     * @returns True if loaded from database, false if created in memory
+     */
+    get isLoaded(): boolean;
+    /**
+     * Mark the spec as having changes.
+     *
+     * Call this method after modifying the spec to indicate that changes need to be saved.
+     * The spec is automatically marked dirty when created with the constructor, but if you
+     * load a spec and then modify it, you should call this method.
+     *
+     * @example
+     * ```typescript
+     * const spec = await AgentSpecSync.LoadFromDatabase('agent-uuid', contextUser);
+     * spec.spec.Description = 'New description';
+     * spec.markDirty();
+     * await spec.SaveToDatabase();
+     * ```
+     */
+    markDirty(): void;
+}
+//# sourceMappingURL=agent-spec-sync.d.ts.map

package/dist/agent-spec-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-spec-sync.d.ts","sourceRoot":"","sources":["../src/agent-spec-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,QAAQ,EAEX,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EACH,SAAS,EAGZ,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,aAAa;IACtB;;OAEG;IACI,IAAI,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAkB;IAEnC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAkB;IAElC;;;OAGG;IACH,OAAO,CAAC,YAAY,CAAC,CAAW;IAEhC;;;;;;;;;;OAUG;gBACS,IAAI,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,EAAE,QAAQ;IAmB7D;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACU,gBAAgB,CACzB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,QAAQ,EACtB,gBAAgB,GAAE,OAAc,GACjC,OAAO,CAAC,aAAa,CAAC;IAMzB;;;;;;;;;;;;;;;;;OAiBG;WACU,UAAU,CACnB,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,QAAQ,EACtB,gBAAgB,GAAE,OAAc,GACjC,OAAO,CAAC,aAAa,CAAC;IAyBzB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,QAAQ,GAAG,aAAa;IAM7E;;;;;;;;;;;OAWG;YACW,gBAAgB;IAkE9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB;IA8D5B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,cAAc,CAAC,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB/D;;;;;;;OAOG;YACW,eAAe;IAsF7B;;;;;;;;;;OAUG;YACW,WAAW;IAuCzB;;;;;;;;;;OAUG;YACW,aAAa;IAc3B;;;;;;;;;;;OAWG;YACW,iBAAiB;IA4B/B;;;;;;;;;;OAUG;YACW,mBAAmB;IA+CjC;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAoCtB;;;;;;;;;;;;;;;OAeG;IACI,MAAM,IAAI,SAAS;IAI1B;;;;OAIG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;OAIG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED;;;;;;;;;;;;;;OAcG;IACI,SAAS,IAAI,IAAI;CAG3B"}