Add CallFunctionMessage and functionResponse.

specification/v0_10/json/client_to_server.json

@@ -1,4 +1,6 @@
 {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2ui.org/specification/v0_10/client_to_server.json",
   "title": "A2UI (Agent to UI) Client-to-Server Event Schema",
   "description": "Describes a JSON payload for a client-to-server event message.",
   "type": "object",
@@ -43,6 +45,31 @@
         "context"
       ]
     },
+    "functionResponse": {
+      "allOf": [
+        {
+          "properties": {
+            "functionCallId": {
+              "$ref": "common_types.json#/$defs/CallId",
+              "description": "Unique ID for the instance of this function. MUST be copied verbatim from the function invocation."
+            },
+            "value": {
+              "description": "The return value of the function invocation.",
+              "type": [
+                "string",
+                "number",
+                "boolean",
+                "array",
+                "object",
+                "null"
+              ]
+            }
+          },
+          "required": ["functionCallId", "value"]
+        }
+      ],
+      "unevaluatedProperties": false
+    },
     "error": {
       "description": "Reports a client-side error.",
       "oneOf": [
@@ -85,9 +112,27 @@
             "surfaceId": {
               "type": "string",
               "description": "The id of the surface where the error occurred."
+            },
+            "functionCallId": {
+              "$ref": "common_types.json#/$defs/CallId",
+              "description": "The unique ID of the function invocation, which must be identical to the value specified in the function invocation."
             }
           },
-          "required": ["code", "surfaceId", "message"],
+          "required": ["code", "message"],
+          "oneOf": [
+            {
+              "required": ["surfaceId"],
+              "not": {
+                "required": ["functionCallId"]
+              }
+            },
+            {
+              "required": ["functionCallId"],
+              "not": {
+                "required": ["surfaceId"]
+              }
+            }
+          ],
           "additionalProperties": true
         }
       ]
@@ -97,6 +142,9 @@
     {
       "required": ["action", "version"]
     },
+    {
+      "required": ["functionResponse", "version"]
+    },
     {
       "required": ["error", "version"]
     }

specification/v0_10/json/common_types.json

@@ -8,6 +8,10 @@
       "type": "string",
       "description": "The unique identifier for a component, used for both definitions and references within the same surface."
     },
+    "CallId": {
+      "type": "string",
+      "description": "The unique identifier for a server initiated function call."
+    },
     "AccessibilityAttributes": {
       "type": "object",
       "description": "Attributes to enhance accessibility when using assistive technologies like screen readers.",
@@ -201,6 +205,15 @@
       "type": "object",
       "description": "Invokes a named function on the client.",
       "properties": {
+        "callableFrom": {
+          "description": "Specifies where this function can be invoked from.",
+          "enum": [
+            "clientOnly",
+            "remoteOnly",
+            "clientOrRemote"
+          ],
+          "default": "clientOnly"
+        },
         "call": {
           "type": "string",
           "description": "The name of the function to call."
@@ -221,15 +234,13 @@
           }
         },
         "returnType": {
-          "type": "string",
           "description": "The expected return type of the function call.",
           "enum": [
-            "string",
-            "number",
-            "boolean",
             "array",
+            "boolean",
+            "number",
             "object",
-            "any",
+            "string",
             "void"
           ],
           "default": "boolean"

specification/v0_10/json/server_to_client.json

@@ -8,7 +8,8 @@
     { "$ref": "#/$defs/CreateSurfaceMessage" },
     { "$ref": "#/$defs/UpdateComponentsMessage" },
     { "$ref": "#/$defs/UpdateDataModelMessage" },
-    { "$ref": "#/$defs/DeleteSurfaceMessage" }
+    { "$ref": "#/$defs/DeleteSurfaceMessage" },
+    { "$ref": "#/$defs/CallFunctionMessage" }
   ],
   "$defs": {
     "CreateSurfaceMessage": {
@@ -59,7 +60,6 @@
               "type": "string",
               "description": "The unique identifier for the UI surface to be updated."
             },
-
             "components": {
               "type": "array",
               "description": "A list containing all UI components for the surface.",
@@ -127,6 +127,45 @@
       },
       "required": ["deleteSurface", "version"],
       "additionalProperties": false
+    },
+    "CallFunctionMessage": {
+      "type": "object",
+      "description": "A function invoked from the server.",
+      "properties": {
+        "version": {
+          "const": "v0.10"
+        },
+        "functionCallId": {
+          "$ref": "common_types.json#/$defs/CallId",
+          "description": "Unique ID for the instance of this function call. MUST be copied verbatim into the functionResponse or error."
+        },
+        "wantResponse": {
+          "type": "boolean",
+          "default": false
+        },
+        "callFunction": {
+          "allOf": [
+            {
+              "$ref": "common_types.json#/$defs/FunctionCall"
+            },
+            {
+              "properties": {
+                "callableFrom": {
+                  "description": "Specifies where this function can be invoked from.",
+                  "enum": [
+                    "remoteOnly",
+                    "clientOrRemote"
+                  ]
+                }
+              }
+            }
+          ],
+          "required": ["call", "returnType", "callableFrom"],
+          "unevaluatedProperties": false
+        }
+      },
+      "required": ["version", "callFunction", "functionCallId"],
+      "additionalProperties": false
     }
   }
 }

specification/v0_10/test/cases/call_function_message.json

@@ -0,0 +1,163 @@
+{
+  "schema": "server_to_client.json",
+  "catalog": "testing_catalog.json",
+  "tests": [
+    {
+      "description": "CallFunctionMessage: Valid with wantResponse",
+      "valid": true,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "openUrl",
+          "args": {
+            "url": "https://example.com"
+          },
+          "returnType": "void",
+          "callableFrom": "clientOrRemote"
+        },
+        "functionCallId": "unique-call-id-123",
+        "wantResponse": true
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Valid with remoteOnly",
+      "valid": true,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "pingServer",
+          "returnType": "void",
+          "callableFrom": "remoteOnly"
+        },
+        "functionCallId": "unique-call-id-123a",
+        "wantResponse": false
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Valid without wantResponse",
+      "valid": true,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "openUrl",
+          "args": {
+            "url": "https://example.com"
+          },
+          "returnType": "void",
+          "callableFrom": "clientOrRemote"
+        },
+        "functionCallId": "unique-call-id-124"
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid (missing callId)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "required",
+          "args": { "value": "bar" },
+          "returnType": "boolean",
+          "callableFrom": "clientOrRemote"
+        }
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid (missing callFunction)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "functionCallId": "unique-call-id-125"
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid (`callableFrom` is clientOnly)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "required",
+          "args": { "value": "bar" },
+          "returnType": "boolean",
+          "callableFrom": "clientOnly"
+        },
+        "functionCallId": "unique-call-id-126"
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid (`callableFrom` is missing)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "required",
+          "args": { "value": "bar" },
+          "returnType": "boolean"
+        },
+        "functionCallId": "unique-call-id-126b"
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid args (nested object in a single value)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "required",
+          "args": {
+            "value": { "nested": "object" }
+          },
+          "returnType": "boolean",
+          "callableFrom": "clientOrRemote"
+        },
+        "functionCallId": "unique-call-id-127"
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid args (array of nested objects)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "required",
+          "args": {
+            "value": [{ "nested": "object" }]
+          },
+          "returnType": "boolean",
+          "callableFrom": "clientOrRemote"
+        },
+        "functionCallId": "unique-call-id-128"
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid returnType (not a scalar)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "required",
+          "args": { "value": "bar" },
+          "returnType": "object",
+          "callableFrom": "clientOrRemote"
+        },
+        "functionCallId": "unique-call-id-129"
+      }
+    },
+    {
+      "description": "CallFunctionMessage: Invalid call to local-only function (required)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "callFunction": {
+          "call": "required",
+          "args": {
+            "value": "test"
+          },
+          "returnType": "boolean",
+          "callableFrom": "clientOrRemote"
+        },
+        "functionCallId": "id-3"
+      }
+    }
+  ]
+}

specification/v0_10/test/cases/client_messages.json

@@ -42,6 +42,42 @@
           "value": "Alice"
         }
       }
+    },
+    {
+      "description": "error: Valid with callId",
+      "valid": true,
+      "data": {
+        "version": "v0.10",
+        "error": {
+          "code": "FUNCTION_FAILED",
+          "functionCallId": "unique-call-id-132",
+          "message": "Something went wrong"
+        }
+      }
+    },
+    {
+      "description": "error: Invalid with BOTH callId and surfaceId",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "error": {
+          "code": "FUNCTION_FAILED",
+          "functionCallId": "unique-call-id-133",
+          "surfaceId": "main",
+          "message": "Something went wrong"
+        }
+      }
+    },
+    {
+      "description": "error: Invalid with NEITHER callId nor surfaceId",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "error": {
+          "code": "FUNCTION_FAILED",
+          "message": "Something went wrong"
+        }
+      }
     }
   ]
 }