Merge branch 'next' of github.com:devforth/adminforth into next

Author: yaroslav8765

adminforth/documentation/docs/tutorial/05-Adapters/05-ai-completion-adapters.md

@@ -129,7 +129,7 @@ new CompletionAdapterOpenAIResponses({
 
 You can specify any GPT model you need. The default is `gpt-5-nano` as it is cheapest though may behave weakly.
 
-By default, this adapter uses the OpenAI `responses` API (`v1/responses`) unless `useComplitionApi` is set to `true`. If `useComplitionApi` is `true`, it uses the older Chat Completions API (`v1/chat/completions`). 
+By default, this adapter uses the OpenAI `responses` API (`v1/responses`) unless `useCompletionApi` is set to `true`. If `useCompletionApi` is `true`, it uses the older Chat Completions API (`v1/chat/completions`). 
 
 
 ### Using with OpenAI-compatible API providers (for example based on self-hosted vLLM docker images)
@@ -141,25 +141,25 @@ new CompletionAdapterOpenAIResponses({
   openAiApiKey: process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN as string,
   baseUrl: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
   model: 'gpt-oss-20b',
-  useComplitionApi: true,
+  useCompletionApi: true,
   extraRequestBodyParameters: {
     store: false,
   },
 }),
 ```
 
-If `useComplitionApi` is omitted, the adapter keeps the current default behavior:
+If `useCompletionApi` is omitted, the adapter keeps the current default behavior:
 
 - official OpenAI uses the `responses` API
 - custom `baseUrl` providers use the Chat Completions API. 
 
-This is because many OpenAI-compatible providers do not yet support the `responses` API or support it unstably (for example OVH AI Endpoints still - Apr 2026 does not fully support the `responses`, so `useComplitionApi: false` may work unstably there, though you can re-test it by manually enabling it by setting `useComplitionApi: true` and checking if it works).
+This is because many OpenAI-compatible providers do not yet support the `responses` API or support it unstably (for example OVH AI Endpoints still - Apr 2026 does not fully support the `responses`, so `useCompletionApi: false` may work unstably there, though you can re-test it by manually enabling it by setting `useCompletionApi: true` and checking if it works).
 Any 3rd-party API providers might have next reasones of pure `responses` API compatibility:
 
 1) If they use vLLM open-source software under the hood they might have outdated version
 2) Custom non-vLLM implmentation might have reliable chat API implementation while give less priority to responses API as it is more complex and new.
 
-We recommend you to try responses API first by setting `false` in `useComplitionApi` because it gives rich features set, including summarization and better structured outputs, and if it does not work for your provider, then set it to `true` to have less features but working implementation.
+We recommend you to try responses API first by setting `false` in `useCompletionApi` because it gives rich features set, including summarization and better structured outputs, and if it does not work for your provider, then set it to `true` to have less features but working implementation.
 
 
 

adminforth/documentation/docs/tutorial/08-Plugins/01-agent.md

@@ -579,18 +579,18 @@ completionAdapter: new CompletionAdapterOpenAIResponses({
 
 However some of 3rd party providers might serve outdated vLLM and still don't fully support the Responses API needed for langchain internal implmentation, for example [OVH AI Endpoints](https://www.ovhcloud.com/en/public-cloud/ai-endpoints/) in Responses mode still don't play well with langchain proxy (25 Apr 2026)
 
-In that case you can try to use the OpenAI Complition API mode of the plugin, which is less efficient but more compatible with older APIs, you can force Chat Completions API mode with `useComplitionApi: true`:
+In that case you can try to use the OpenAI Chat Completions API mode of the plugin, which is less efficient but more compatible with older APIs, you can force Chat Completions API mode with `useCompletionApi: true`:
 
 ```ts
 completionAdapter: new CompletionAdapterOpenAIResponses({
   openAiApiKey: process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN as string,
   baseUrl: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
   model: 'gpt-oss-120b',
-  useComplitionApi: true,
+  useCompletionApi: true,
 })
 ```
 
-OVH AI Endpoints still does not fully support the OpenAI `responses` API, so `useComplitionApi: false` may work unstably there.
+OVH AI Endpoints still does not fully support the OpenAI `responses` API, so `useCompletionApi: false` may work unstably there.
 
 
 ## Turn on audio chat support
@@ -655,6 +655,29 @@ To define a custom tool, register an API endpoint with `admin.express.endpoint`.
 
 By default, `admin.express.endpoint` applies AdminForth authorization. The endpoint handler receives `adminUser` from the user who is controlling the agent. In other words, all permissions and access rights of the agent are defined by that admin user. At the same time, actions done by the agent are automatically attributed in the audit log to the admin user who is controlling the agent.
 
+If a tool is risky, you can attach AdminForth agent metadata directly to the endpoint with the `agent` field.
+
+```ts
+type AgentRiskLevel = 'safe' | 'danger';
+
+type AgentToolMeta = {
+  riskLevel?: AgentRiskLevel;
+  confirmation?: {
+    title?: string;
+    message?: string;
+    confirmLabel?: string;
+  };
+};
+```
+
+Use it in `.endpoint(...)` like this:
+
+- `riskLevel: 'safe'` marks the tool as low-risk.
+- `riskLevel: 'danger'` marks the tool as dangerous.
+- `confirmation` customizes the confirmation dialog shown before the tool is executed.
+
+This metadata is rendered into the generated OpenAPI document, so the agent can understand that a tool is dangerous and requires an explicit confirmation UI before execution.
+
 This example uses the same email adapter pattern shown in the Email Invite and Email Password Reset plugins. The transport below uses Mailgun only to keep the snippet short; you can replace it with SES or any other adapter from [List of adapters](/docs/tutorial/ListOfAdapters/).
 
 ```ts title="./api.ts"
@@ -691,6 +714,14 @@ export function initApi(app: Express, admin: IAdminForth) {
     method: 'POST',
     path: '/send_email_to_user',
     description: 'Send an email to one AdminForth user by id. Use this after the user row is resolved.',
+    agent: {
+      riskLevel: 'danger',
+      confirmation: {
+        title: 'Send email to user',
+        message: 'This action will send a real email to the selected user.',
+        confirmLabel: 'Send email',
+      },
+    },
     request_schema: {
       type: 'object',
       additionalProperties: false,

adminforth/documentation/docs/tutorial/08-Plugins/27-dashboard.md

@@ -332,7 +332,7 @@ query:
 
 ### Chart With Multiple Sources
 
-Use `query.steps` when funnel steps come from different resources. Each step returns one row with `name` and the metric alias.
+Use `query.source: steps` when chart data comes from different resources. Each step returns one row with `name`, `resource`, and the selected aggregate aliases.
 
 ```yaml
 label: Sales Funnel
@@ -343,27 +343,68 @@ chart:
   type: funnel
   title: Sales funnel
 query:
+  source: steps
   steps:
     - name: Leads
       resource: leads
-      metric:
-        agg: count
-        as: value
+      select:
+        - agg: count
+          as: value
     - name: Qualified
       resource: leads
-      metric:
-        agg: count
-        as: value
+      select:
+        - agg: count
+          as: value
       filters:
         and:
           - field: status
             eq: qualified
     - name: Customers
       resource: orders
-      metric:
-        agg: count_distinct
-        field: customer_id
-        as: value
+      select:
+        - agg: count_distinct
+          field: customer_id
+          as: value
+```
+
+For the same numeric buckets across multiple resources, add `query.bucket` and render the result as a stacked bar chart. The dashboard runs every step once per bucket and returns rows with `label`, `name`, `resource`, and the aggregate aliases:
+
+```yaml
+label: Cars by Price Range and Database
+target: chart
+size: wide
+height: 360
+chart:
+  type: stacked_bar
+  x:
+    field: label
+  y:
+    field: count
+  series:
+    field: name
+query:
+  source: steps
+  bucket:
+    field: price
+    buckets:
+      - label: Budget
+        max: 3500
+      - label: Mid-range
+        min: 3500
+        max: 7000
+      - label: Premium
+        min: 7000
+  steps:
+    - name: SQLite
+      resource: cars_sl
+      select:
+        - agg: count
+          as: count
+    - name: MySQL
+      resource: cars_mysql
+      select:
+        - agg: count
+          as: count
 ```
 
 ### KPI Card

adminforth/modules/restApi.ts

@@ -1927,6 +1927,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         method: 'POST',
         path: '/create_record',
       description: 'Creates a new record in the specified resource. The endpoint validates create permissions, required fields, hidden or backend-only field rules, polymorphic foreign keys, and resource hooks before persisting and returning the created primary key.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: createRecordRequestSchema,
       response_schema: createRecordResponseSchema,
         handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
@@ -2075,9 +2078,12 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         }
     });
     server.endpoint({
-        method: 'POST',
-        path: '/update_record',
+      method: 'POST',
+      path: '/update_record',
       description: 'Updates an existing record by primary key. The endpoint validates edit permissions, current record existence, hidden, backend-only, and read-only field rules, polymorphic foreign keys, and resource hooks before saving changes.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: updateRecordRequestSchema,
       response_schema: updateRecordResponseSchema,
         handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
@@ -2216,9 +2222,12 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         }
     });
     server.endpoint({
-        method: 'POST',
-        path: '/delete_record',
+      method: 'POST',
+      path: '/delete_record',
       description: 'Deletes an existing record by primary key. The endpoint validates delete permissions, loads the current record, executes configured cascade child deletion, and then removes the record.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: deleteRecordRequestSchema,
       response_schema: deleteRecordResponseSchema,
         handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
@@ -2305,6 +2314,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/start_custom_action',
       description: 'Executes a custom resource action for a single record. The endpoint validates the resource, action existence, and action permissions, then either returns a redirect URL or executes the action handler and returns its result together with action context.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: startCustomActionRequestSchema,
       response_schema: startCustomActionResponseSchema,
       handler: async ({ body, adminUser, tr, cookies, response, headers }) => {
@@ -2361,6 +2373,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/start_custom_bulk_action',
       description: 'Executes a custom resource action in bulk mode for multiple records. The endpoint validates the resource, action existence, bulk handler availability, and permissions, then runs the bulk handler and returns its result together with action context.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: startCustomBulkActionRequestSchema,
       response_schema: startCustomBulkActionResponseSchema,
       handler: async ({ body, adminUser, tr, response, cookies, headers }) => {

adminforth/servers/express.ts

@@ -479,6 +479,7 @@ class ExpressServer implements IExpressHttpServer {
           method: method.toUpperCase(),
           path: routePath,
           description: schema.description,
+          agent: schema.agent,
           request_schema: schema.request,
           response_schema: schema.response,
           meta: schema.meta,
@@ -568,6 +569,7 @@ class ExpressServer implements IExpressHttpServer {
       request_schema,
       response_schema,
       responce_schema,
+      agent,
       target='json'
     } = options;
     if (!path.startsWith('/')) {
@@ -583,6 +585,7 @@ class ExpressServer implements IExpressHttpServer {
         description,
         request_schema,
         response_schema: normalizedResponseSchema,
+        agent,
         handler,
       })
       : null;

adminforth/servers/openapi.ts

@@ -56,6 +56,7 @@ class OpenApiRegistry implements IOpenApiRegistry {
       method: options.method.toLowerCase(),
       path: options.path,
       description: options.description,
+      agent: options.agent,
       request_schema: options.request_schema,
       response_schema: responseSchema,
       meta: options.meta,

adminforth/types/Back.ts

@@ -5,7 +5,6 @@ import type { ZodType } from 'zod';
 
 import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections, AllowedActionsEnum, AdminForthResourcePages,
   type AdminForthComponentDeclaration, 
-  type AdminForthResourceCommon, 
   type AdminUser, type AllowedActionsResolved, 
   type AdminForthBulkActionCommon, 
   type AdminForthForeignResourceCommon,
@@ -59,13 +58,18 @@ export interface IAdminForthAuthenticatedEndpointHandlerInput extends IAdminFort
   adminUser: AdminUser;
 }
 
+export type AgentToolMeta = {
+  isDangerous?: boolean;
+};
+
 export interface IAdminForthEndpointOptionsBase {
   method: string,
   path: string,
   description?: string,
   request_schema?: AnySchemaObject,
   response_schema?: AnySchemaObject,
   responce_schema?: AnySchemaObject,
+  agent?: AgentToolMeta,
   meta?: Record<string, unknown>,
   target?: 'json' | 'upload',
 }
@@ -102,6 +106,11 @@ export interface IAdminForthExpressRouteSchema {
    */
   response?: AdminForthExpressSchemaInput;
 
+  /**
+   * AdminForth agent metadata.
+   */
+  agent?: AgentToolMeta;
+
   /**
    * Internal metadata for AdminForth integrations. This is not rendered in the OpenAPI document.
    */
@@ -112,6 +121,7 @@ export interface IRegisteredApiSchema {
   method: string;
   path: string;
   description?: string;
+  agent?: AgentToolMeta;
   meta?: Record<string, unknown>;
   request_schema?: AnySchemaObject;
   response_schema?: AnySchemaObject;

dev-demo/Taskfile.yaml

@@ -43,6 +43,8 @@ vars:
     - "adminforth-oauth-adapter-keycloak"
     - "adminforth-oauth-adapter-microsoft"
     - "adminforth-oauth-adapter-twitch"
+    - "adminforth-oauth-adapter-telegram"
+    - "adminforth-chat-surface-adapter-telegram"
     - "adminforth-image-generation-adapter-openai"
     - "adminforth-storage-adapter-amazon-s3"
     - "adminforth-storage-adapter-local"