Add AI agent and enhance validation schemas

Introduces AI agent, tool, and knowledge base schemas in a new file for AI protocol support. Refactors validation rule schemas to use discriminated unions for multiple validation types (script, uniqueness, state machine, format) and adds severity and message fields. Updates index exports to include the new AI agent schema.

Author: hotlong

packages/spec/src/ai/agent.zod.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+
+/**
+ * AI Model Configuration
+ */
+export const AIModelConfigSchema = z.object({
+  provider: z.enum(['openai', 'azure_openai', 'anthropic', 'local']).default('openai'),
+  model: z.string().describe('Model name (e.g. gpt-4, claude-3-opus)'),
+  temperature: z.number().min(0).max(2).default(0.7),
+  maxTokens: z.number().optional(),
+  topP: z.number().optional(),
+});
+
+/**
+ * AI Tool Definition
+ * References to Actions, Flows, or Objects available to the Agent.
+ */
+export const AIToolSchema = z.object({
+  type: z.enum(['action', 'flow', 'query', 'vector_search']),
+  name: z.string().describe('Reference name (Action Name, Flow Name)'),
+  description: z.string().optional().describe('Override description for the LLM'),
+});
+
+/**
+ * AI Knowledge Base
+ * RAG configuration.
+ */
+export const AIKnowledgeSchema = z.object({
+  topics: z.array(z.string()).describe('Topics/Tags to recruit knowledge from'),
+  indexes: z.array(z.string()).describe('Vector Store Indexes'),
+});
+
+/**
+ * AI Agent Schema
+ * Definition of an autonomous agent specialized for a domain.
+ */
+export const AgentSchema = z.object({
+  /** Identity */
+  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Agent unique identifier'),
+  label: z.string().describe('Agent display name'),
+  avatar: z.string().optional(),
+  role: z.string().describe('The persona/role (e.g. "Senior Support Engineer")'),
+  
+  /** Cognition */
+  instructions: z.string().describe('System Prompt / Prime Directives'),
+  model: AIModelConfigSchema.optional(),
+  
+  /** Capabilities */
+  tools: z.array(AIToolSchema).optional().describe('Available tools'),
+  knowledge: AIKnowledgeSchema.optional().describe('RAG access'),
+  
+  /** Interface */
+  active: z.boolean().default(true),
+  access: z.array(z.string()).optional().describe('Who can chat with this agent'),
+});
+
+export type Agent = z.infer<typeof AgentSchema>;
+export type AITool = z.infer<typeof AIToolSchema>;

packages/spec/src/data/validation.zod.ts

@@ -1,25 +1,67 @@
 import { z } from 'zod';
 
 /**
- * Schema for Validation Rules.
- * Ensures data integrity by preventing saves when conditions aren't met.
+ * Base Validation Rule
  */
-export const ValidationRuleSchema = z.object({
-  /** Machine name of the rule */
+const BaseValidationSchema = z.object({
   name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Unique rule name'),
-  
-  /** 
-   * The condition that triggers the error.
-   * If this evaluates to TRUE, the validation FAILS and the error is shown.
-   * Example: "amount < 0" (Prevents negative amounts)
-   */
-  error_condition: z.string().describe('Formula expression. If TRUE, validation fails.'),
-  
-  /** The error message displayed to the user */
-  error_message: z.string().describe('Error message to display to the user'),
-  
-  /** Active status of the rule */
-  active: z.boolean().default(true).describe('Whether this rule is active'),
+  active: z.boolean().default(true),
+  severity: z.enum(['error', 'warning', 'info']).default('error'),
+  message: z.string().describe('Error message to display'),
 });
 
+/**
+ * 1. Script/Expression Validation
+ * Generic formula-based validation.
+ */
+export const ScriptValidationSchema = BaseValidationSchema.extend({
+  type: z.literal('script'),
+  condition: z.string().describe('Formula expression. If TRUE, validation fails. (e.g. amount < 0)'),
+});
+
+/**
+ * 2. Uniqueness Validation
+ * specialized optimized check for unique constraints.
+ */
+export const UniquenessValidationSchema = BaseValidationSchema.extend({
+  type: z.literal('unique'),
+  fields: z.array(z.string()).describe('Fields that must be combined unique'),
+  scope: z.string().optional().describe('Formula condition for scope (e.g. active = true)'),
+  caseSensitive: z.boolean().default(true),
+});
+
+/**
+ * 3. State Machine Validation
+ * State transition logic.
+ */
+export const StateMachineValidationSchema = BaseValidationSchema.extend({
+  type: z.literal('state_machine'),
+  field: z.string().describe('State field (e.g. status)'),
+  transitions: z.record(z.array(z.string())).describe('Map of { OldState: [AllowedNewStates] }'),
+});
+
+/**
+ * 4. Value Format Validation
+ * Regex or specialized formats.
+ */
+export const FormatValidationSchema = BaseValidationSchema.extend({
+  type: z.literal('format'),
+  field: z.string(),
+  regex: z.string().optional(),
+  format: z.enum(['email', 'url', 'phone', 'json']).optional(),
+});
+
+/**
+ * Master Validation Rule Schema
+ */
+export const ValidationRuleSchema = z.discriminatedUnion('type', [
+  ScriptValidationSchema,
+  UniquenessValidationSchema,
+  StateMachineValidationSchema,
+  FormatValidationSchema
+]);
+
 export type ValidationRule = z.infer<typeof ValidationRuleSchema>;
+export type ScriptValidation = z.infer<typeof ScriptValidationSchema>;
+export type UniquenessValidation = z.infer<typeof UniquenessValidationSchema>;
+export type StateMachineValidation = z.infer<typeof StateMachineValidationSchema>;

packages/spec/src/index.ts

@@ -16,6 +16,9 @@ export * from './data/workflow.zod';
 export * from './data/flow.zod';
 export * from './data/dataset.zod';
 
+// AI Protocol (Agent, RAG)
+export * from './ai/agent.zod';
+
 // UI Protocol (Layout, Navigation, Interaction)
 export * from './ui/app.zod';
 export * from './ui/view.zod';