Merge pull request #93 from g4-api/development

Development

Author: gravity-api

src/G4.Services.Domain.V4/Extensions/LocalExtensions.cs

@@ -221,6 +221,7 @@ public McpToolModel ConvertToTool()
                     Description = description,
                     QualifiedName = manifest.Key,
                     Name = name,
+                    Namespace = manifest.Namespace,
                     Metadata = new McpToolModel.ToolMetadataModel
                     {
                         Description = string.Join(Environment.NewLine, manifest.Summary),

src/G4.Services.Domain.V4/Models.Schema/SendRulesInputSchema.cs

@@ -0,0 +1,43 @@
+using Swashbuckle.AspNetCore.Annotations;
+
+namespace G4.Services.Domain.V4.Models.Schema
+{
+    /// <summary>
+    /// Input schema for starting the execution of a collection of rules within an active G4 driver session.
+    /// Requires a driver session identifier, the ordered rule definitions to execute, and an authorization token.
+    /// </summary>
+    [SwaggerSchema(description: "Schema for starting the execution of a collection of rules within an active G4 driver session.")]
+    public class SendRulesInputSchema
+    {
+        /// <summary>
+        /// Gets or sets the driver session identifier.
+        /// Specifies the active session in which the rules should be executed.
+        /// </summary>
+        [SwaggerSchema(description: "The unique session ID associated with the current browser session. " +
+            "This ID is used to retrieve the appropriate browser driver for interacting with " +
+            "the session and performing automation tasks.")]
+        public string DriverSession { get; set; }
+
+        /// <summary>
+        /// Gets or sets the user intent or natural-language request
+        /// that describes the purpose of the rules being sent.
+        /// </summary>
+        [SwaggerSchema(description: "The user intent or natural-language request that describes the purpose of the rules being sent.")]
+        public IntentModel Intent { get; set; }
+
+        /// <summary>
+        /// Gets or sets the ordered collection of rule definitions to execute.
+        /// This may be a structured array representing the automation rule logic.
+        /// </summary>
+        [SwaggerSchema(description: "The ordered collection of G4 rules to be executed, including their parameters and configuration.")]
+        public object Rules { get; set; }
+
+        /// <summary>
+        /// Gets or sets the authorization token required by the G4 engine
+        /// to validate and execute the rule request.
+        /// </summary>
+        [SwaggerSchema(description: "The G4 Authentication token used to authenticate the session initiation process. " +
+            "This is required to authorize the session creation.")]
+        public string Token { get; set; }
+    }
+}

src/G4.Services.Domain.V4/Models/McpToolModel.cs

@@ -36,6 +36,11 @@ public class McpToolModel
         /// </summary>
         public string Name { get; set; }
 
+        /// <summary>
+        /// Gets or sets the namespace that owns the tool.
+        /// </summary>
+        public string Namespace { get; set; }
+
         /// <summary>
         /// Gets or sets additional metadata about the tool.
         /// </summary>

src/G4.Services.Domain.V4/Repositories/IToolsRepository.cs

@@ -137,6 +137,15 @@ public interface IToolsRepository
         /// <returns>An object representing the outcome of the rule execution. The exact structure of the result is defined by the G4 engine.</returns>
         object SendRule(SendRuleInputSchema schema);
 
+        /// <summary>
+        /// Sends an ordered collection of rules for execution within an active G4 driver session.
+        /// All rules are executed sequentially as a single job against the specified driver session,
+        /// sharing the same page and session state.
+        /// </summary>
+        /// <param name="schema">The input schema that includes the driver session identifier, the ordered rule definitions to execute, and the authorization token required by the G4 engine.</param>
+        /// <returns>An object representing the outcome of the rule collection execution, including the ordered per-rule output. The exact structure of the result is defined by the G4 engine.</returns>
+        object SendRules(SendRulesInputSchema schema);
+
         /// <summary>
         /// Starts a new driver session using the provided input schema.  
         /// The session is created through the G4 engine using the driver configuration

src/G4.Services.Domain.V4/Repositories/McpRepository.cs

@@ -96,7 +96,7 @@ static ToolOutputSchema FindTool(
                 {
                     response.Result = new
                     {
-                        Tool = tool.ClientTool
+                        Tool = tool
                     };
                 }
 

src/G4.Services.Domain.V4/Repositories/ToolsRepository.cs

@@ -134,7 +134,7 @@ public object CallTool(JsonElement parameters)
                 { Name: "g4.ConvertToRule" } => new { options.Rule },
 
                 // Built-in: Finds and returns relevant examples based on the provided intent and tool filters.
-                { Name: "g4.FindExamples" } => FindExamples(options),
+                { Name: "g4.FindExamples" } => FindExamples(options.Arguments),
 
                 // Built-in: Finds and returns metadata about a tool by its name.
                 { Name: "g4.FindTool" } => FindTool(options),
@@ -162,6 +162,9 @@ public object CallTool(JsonElement parameters)
                 // Built-in: Retrieves the locator for a specific element on the page.
                 { Name: "g4.ResolveLocator" } => ResolveLocator(options),
 
+                // Built-in: Executes an ordered collection of rules as a single job in one driver session.
+                { Name: "g4.SendRules" } => SendRules(options),
+
                 // Built-in: Starts a new G4 browser automation session.
                 { Name: "g4.StartSession" } => StartSession(options),
 
@@ -219,15 +222,6 @@ public object FindExamples(ExamplesQueryModel query)
             };
         }
 
-        // Unwraps the raw "arguments" payload from an MCP tool-call invocation and delegates
-        // to the public, strongly-typed FindExamples(JsonElement) overload. This gives the
-        // g4.FindExamples switch arm in CallTool the same "Xxx(options)" call shape as every
-        // other built-in tool handler, instead of reaching into options.Arguments directly.
-        private object FindExamples(InvokeOptions options)
-        {
-            return FindExamples(options.Arguments);
-        }
-
         /// <inheritdoc />
         public McpToolModel FindTool(string intent, string toolName)
         {
@@ -488,6 +482,42 @@ public object SendRule(SendRuleInputSchema schema)
             return SendRule(options);
         }
 
+        /// <inheritdoc />
+        public object SendRules(SendRulesInputSchema schema)
+        {
+            // Wrap the incoming rule collection in an anonymous arguments object so it can be
+            // serialized and converted through the standard rule conversion pipeline.
+            var arguments = new
+            {
+                schema.Rules
+            };
+
+            // Serialize the arguments payload using the shared JSON settings.
+            var json = JsonSerializer.Serialize(value: arguments, AppSettings.JsonOptions);
+
+            // Parse the serialized payload into a JsonElement so it can be passed
+            // into the rule conversion routine.
+            var jsonElement = JsonDocument.Parse(json).RootElement;
+
+            // Build the invocation options using the driver session, token,
+            // tool catalog, and shared runtime services required by the G4 engine.
+            var options = new InvokeOptions
+            {
+                Arguments = jsonElement,
+                Buffer = _buffer,
+                DriverSession = schema.DriverSession,
+                G4Client = _client,
+                HttpClient = _httpClient,
+                Intent = schema.Intent,
+                Sessions = _sessions,
+                Token = schema.Token,
+                Tools = _tools
+            };
+
+            // Delegate the rule collection execution to the G4 engine and return its result.
+            return SendRules(options);
+        }
+
         /// <inheritdoc />
         public void SyncTools()
         {
@@ -538,6 +568,18 @@ private static ActionRuleModel ConvertToRule(
                 ? ruleOut
                 : JsonDocument.Parse("{}").RootElement;
 
+            // Delegate the actual conversion to the shared single-rule routine.
+            return ConvertRuleData(ruleData, intent, tools);
+        }
+
+        // Converts a single rule-data JSON object (tool name, parameters, and properties)
+        // into a G4 action rule model, resolving the plugin name from the tool registry and
+        // attaching the supplied intent to the rule's capabilities.
+        private static ActionRuleModel ConvertRuleData(
+            JsonElement ruleData,
+            IntentModel intent,
+            ConcurrentDictionary<string, McpToolModel> tools)
+        {
             // Retrieve the "name" of the tool to be invoked. Defaults to null if not provided.
             var includes = new[] { "tool_name", "toolName", "name", "tool" };
             var toolName = includes
@@ -553,9 +595,6 @@ private static ActionRuleModel ConvertToRule(
                 ? parametersOut
                 : JsonDocument.Parse("{}").RootElement;
 
-            // Format the parameters into a command-line style string (e.g., "--param1:value1 --param2:value2").
-            var parametersCli = FormatParameters(parameters);
-
             // Get the properties from the ruleData, defaulting to a JSON object with the plugin name if not provided.
             var properties = ruleData.TryGetProperty("toolProperties", out var propertiesOut)
                 ? propertiesOut.GetRawText()
@@ -573,10 +612,15 @@ private static ActionRuleModel ConvertToRule(
             // Set the PluginName property of the rule to the retrieved plugin name
             rule.PluginName = pluginName;
 
-            // Set the Argument property of the rule to the formatted parameters if provided
-            rule.Argument = string.IsNullOrEmpty(parametersCli) || parametersCli.Equals("{{$ }}")
-                ? rule.Argument
-                : parametersCli;
+            // Preserve an explicitly supplied G4 expression and synthesize one only as a fallback.
+            if (string.IsNullOrWhiteSpace(rule.Argument))
+            {
+                var parametersCli = FormatParameters(parameters);
+                if (!string.IsNullOrEmpty(parametersCli) && !parametersCli.Equals("{{$ }}"))
+                {
+                    rule.Argument = parametersCli;
+                }
+            }
 
             // Return the created rule
             return rule;
@@ -590,23 +634,20 @@ static string FormatParameters(JsonElement parameters)
                     return string.Empty;
                 }
 
-                // Build a case-insensitive dictionary of name → textual value.
-                // $"{i.Value}" calls JsonElement.ToString() (see boolean casing note above).
-                var parametersObject = parameters
+                // Expand arrays into repeated switches, as required by the G4 parameter schema.
+                var parametersCollection = parameters
                     .EnumerateObject()
-                    .ToDictionary(i => i.Name, i => $"{i.Value}", StringComparer.OrdinalIgnoreCase);
+                    .SelectMany(parameter => parameter.Value.ValueKind == JsonValueKind.Array
+                        ? parameter.Value
+                            .EnumerateArray()
+                            .Select(value => new KeyValuePair<string, string>(parameter.Name, $"{value}"))
+                        : [new KeyValuePair<string, string>(parameter.Name, $"{parameter.Value}")]);
 
-                // Round-trip through System.Text.Json to apply G4JsonOptions policies (e.g., snake_case keys).
-                var json = JsonSerializer.Serialize(value: parametersObject, options: AppSettings.JsonOptions);
-                var parametersCollection = JsonSerializer.Deserialize<Dictionary<string, string>>(
-                    json,
-                    options: AppSettings.JsonOptions)!;
-
-                // Convert keys to PascalCase and render as --Key[:Value] (omit :Value when empty).
+                // Render each scalar value as --Key[:Value] and each array item as its own switch.
                 var parametersExpression = parametersCollection
-                    .Select(i =>
-                        $"--{i.Key}" +
-                        (string.IsNullOrEmpty(i.Value) ? "" : $":{i.Value}"))
+                    .Select(parameter =>
+                        $"--{parameter.Key}" +
+                        (string.IsNullOrEmpty(parameter.Value) ? "" : $":{parameter.Value}"))
                     .ToArray();
 
                 // Wrap with G4 template delimiters.
@@ -726,6 +767,7 @@ static McpToolModel[] GetSystemTools()
                             ClientTool = clientTool,
                             QualifiedName = $"system.{clientTool.Name}",
                             Name = clientTool.Name,
+                            Namespace = "G4.System",
                             Description = clientTool.Description,
                             Metadata = new()
                             {
@@ -776,10 +818,10 @@ private static object FindTool(InvokeOptions options)
                 ? tool
                 : options.Tools.Values.FirstOrDefault(i => i.QualifiedName.Equals(toolName, StringComparison.OrdinalIgnoreCase));
 
-            // Return the matched tool when a tool name was provided.
-            // Return null when the caller did not supply any tool name.
-            return !string.IsNullOrEmpty(toolName)
-                ? new { Tool = tool.ClientTool }
+            // Return the complete authoritative tool model when it was found.
+            // Return null when the caller did not supply a valid tool name.
+            return !string.IsNullOrEmpty(toolName) && tool != null
+                ? new { Tool = tool }
                 : null;
         }
 
@@ -1154,6 +1196,87 @@ private static object SendRule(InvokeOptions options)
             };
         }
 
+        // Executes an ordered collection of rules as a single job within one driver session,
+        // and retrieves the response, including the driver session and the ordered per-rule output.
+        private static object SendRules(InvokeOptions options)
+        {
+            // Read the "rules" argument and reject the request when it is missing or not an array,
+            // mirroring the tool's required "rules" argument as declared in its input schema.
+            if (!options.Arguments.TryGetProperty("rules", out var rulesElement) ||
+                rulesElement.ValueKind != JsonValueKind.Array)
+            {
+                throw new ArgumentException("The rules argument is required and must be a non-empty array.");
+            }
+
+            // Convert every rule-data entry into an executable G4 action rule, preserving order.
+            var rules = rulesElement
+                .EnumerateArray()
+                .Select(ruleData => ConvertRuleData(ruleData, options.Intent, options.Tools))
+                .ToArray();
+
+            // Reject an empty collection so the engine is not invoked with a job that has no rules.
+            if (rules.Length == 0)
+            {
+                throw new ArgumentException("The rules argument is required and must be a non-empty array.");
+            }
+
+            // Create a single automation model whose only job carries every converted rule in order.
+            var automation = NewAutomation(options.DriverSession, options.Token, rules);
+
+            // Invoke the automation process using the client and retrieve the response.
+            var response = options.G4Client.Automation.Invoke(automation);
+
+            // Extract the session object from the response, ensuring we track the latest session.
+            var session = response.Values.Last().Sessions.Last();
+
+            // Add the session to the sessions dictionary to keep track of the active session.
+            options.Sessions[session.Key] = session.Value;
+
+            // Add one property-backed response entry per rule so later MCP serialization preserves the buffer values.
+            var buffer = options.Buffer.GetValueOrDefault(key: session.Key, defaultValue: null);
+            var timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
+            for (var i = 0; i < rules.Length; i++)
+            {
+                buffer?.Add(new BufferResponseModel.BufferItem
+                {
+                    Timestamp = timestamp + i,
+                    Rule = rules[i]
+                });
+            }
+
+            // Retrieve the complete set of plugin responses for the executed rule collection.
+            var ruleResponse = session
+                .Value
+                .ResponseTree
+                .Stages.Last()
+                .Jobs.Last()
+                .Plugins;
+
+            // Get the current buffer for the session, defaulting to an empty list if none exists.
+            var bufferOut = buffer ?? [];
+
+            // If the last rule closes the browser, clean up the session and buffer.
+            if (rules[^1].PluginName.Equals("CloseBrowser", StringComparison.OrdinalIgnoreCase))
+            {
+                // Remove the session from the sessions dictionary when closing the browser.
+                options.Sessions.TryRemove(session.Key, out _);
+
+                // Clear the buffer associated with the session key.
+                options.Buffer.TryRemove(session.Key, out bufferOut);
+            }
+
+            // Return an anonymous object containing the session key and the ordered rule response values.
+            return new
+            {
+                DriverSession = session.Key,
+                Value = new
+                {
+                    Buffer = bufferOut.OrderBy(i => i.Timestamp).Select(i => i.Rule),
+                    Response = ruleResponse
+                }
+            };
+        }
+
         // Starts a new G4 session by invoking the automation process with the provided parameters.
         // The session information is returned, and the session is added to the provided dictionary of active sessions.
         private static object StartSession(InvokeOptions options)
@@ -1174,8 +1297,6 @@ private static object StartSession(InvokeOptions options)
             // These parameters are required for the automation process to know which browser and driver binaries to use.
             automation.DriverParameters = driverParameters;
 
-            var j = JsonSerializer.Serialize(automation, AppSettings.JsonOptions);
-
             // Invoke the automation process and get the response.
             var response = options.G4Client.Automation.Invoke(automation);