adminizer 5.0.0-build.11 → 5.0.0-build.13

package/lib/admin-links/AdminLinkHandler.d.ts

@@ -0,0 +1,72 @@
+import type { User } from '../../models/User.js';
+import type { Adminizer } from '../Adminizer.js';
+export interface AdminLink {
+    id: string;
+    type: string;
+    name: string;
+    link: string;
+    title?: string;
+    section?: string;
+    accessRightsToken?: string;
+}
+export interface ResolvedAdminLink extends AdminLink {
+    owner: string;
+    title: string;
+}
+/** A placeholder of an admin link template, e.g. `id` in `/model/Test/edit/:id`. */
+export interface AdminLinkTemplateParam {
+    name: string;
+    description?: string;
+}
+/**
+ * A parametrized admin page, e.g. `/admin/model/Test/edit/:id`. Templates are
+ * what makes a record page reachable: the concrete URL only exists once the
+ * caller knows the record id.
+ */
+export interface AdminLinkTemplate {
+    id: string;
+    title: string;
+    /** Absolute admin path with `:param` placeholders. */
+    template: string;
+    description?: string;
+    section?: string;
+    accessRightsToken?: string;
+    /** Placeholder descriptions; placeholders absent here are still required. */
+    params?: AdminLinkTemplateParam[];
+}
+export interface ResolvedAdminLinkTemplate extends AdminLinkTemplate {
+    owner: string;
+    params: AdminLinkTemplateParam[];
+}
+/** Server-side registry of standalone admin pages contributed by applications. */
+export declare class AdminLinkHandler {
+    private readonly adminizer;
+    private readonly links;
+    private readonly templates;
+    constructor(adminizer: Adminizer);
+    add(link: AdminLink, owner?: string): string;
+    remove(id: string, owner?: string): boolean;
+    list(user: User, type?: string): ResolvedAdminLink[];
+    resolve(user: User, type: string, name: string): ResolvedAdminLink | undefined;
+    addTemplate(template: AdminLinkTemplate, owner?: string): string;
+    removeTemplate(id: string, owner?: string): boolean;
+    /**
+     * Every parametrized page this user may open: model record pages, catalog
+     * items, templates registered by apps and any navigation link that carries
+     * placeholders of its own.
+     */
+    listTemplates(user: User): ResolvedAdminLinkTemplate[];
+    /**
+     * Turns a template id (or its title) plus placeholder values into a real
+     * admin URL, rejecting templates this user may not open.
+     */
+    resolveTemplate(user: User, id: string, params?: Record<string, unknown>): string;
+    /** Fills the placeholders of a template with url-encoded values. */
+    buildHref(template: ResolvedAdminLinkTemplate, params?: Record<string, unknown>): string;
+    /** True for paths that change data and therefore must never be navigated to. */
+    isDestructivePath(path: string): boolean;
+    /** Templates derived from the current configuration, catalogs and navigation. */
+    private builtinTemplates;
+    private describeParams;
+    private slug;
+}

package/lib/admin-links/AdminLinkHandler.js

@@ -0,0 +1,175 @@
+/** Segments no template may point at: opening one mutates data. */
+const DESTRUCTIVE_PATH = /\/model\/[^/]+\/remove(\/|$)/i;
+/** Server-side registry of standalone admin pages contributed by applications. */
+export class AdminLinkHandler {
+    adminizer;
+    links = new Map();
+    templates = new Map();
+    constructor(adminizer) {
+        this.adminizer = adminizer;
+    }
+    add(link, owner = 'host') {
+        const type = link.type.trim();
+        const name = link.name.trim();
+        const href = link.link.trim();
+        if (!type || !name || !href)
+            throw new Error('Admin link requires type, name and link');
+        if (!href.startsWith('/'))
+            throw new Error(`Admin link "${name}" must use an absolute admin path`);
+        const id = `${this.slug(type)}:${this.slug(name)}`;
+        if (this.links.has(id))
+            throw new Error(`Admin link "${id}" is already registered`);
+        this.links.set(id, {
+            ...link, id, type, name, link: href, owner,
+            title: link.title?.trim() || name,
+            section: link.section?.trim() || undefined,
+        });
+        return id;
+    }
+    remove(id, owner) {
+        const link = this.links.get(id);
+        if (!link || (owner && link.owner !== owner))
+            return false;
+        return this.links.delete(id);
+    }
+    list(user, type) {
+        const wanted = type ? this.slug(type) : null;
+        return [...this.links.values()].filter((link) => (!wanted || this.slug(link.type) === wanted)
+            && (!link.accessRightsToken || this.adminizer.accessRightsHelper.hasPermission(link.accessRightsToken, user)));
+    }
+    resolve(user, type, name) {
+        const wanted = this.slug(name);
+        return this.list(user, type).find((link) => this.slug(link.name) === wanted || this.slug(link.title) === wanted);
+    }
+    addTemplate(template, owner = 'host') {
+        const id = template.id.trim();
+        const title = template.title.trim();
+        const path = template.template.trim();
+        if (!id || !title || !path)
+            throw new Error('Admin link template requires id, title and template');
+        if (!path.startsWith('/'))
+            throw new Error(`Admin link template "${id}" must use an absolute admin path`);
+        if (this.templates.has(id))
+            throw new Error(`Admin link template "${id}" is already registered`);
+        this.templates.set(id, {
+            ...template, id, title, template: path, owner,
+            description: template.description?.trim() || undefined,
+            section: template.section?.trim() || undefined,
+            params: this.describeParams(path, template.params),
+        });
+        return id;
+    }
+    removeTemplate(id, owner) {
+        const template = this.templates.get(id);
+        if (!template || (owner && template.owner !== owner))
+            return false;
+        return this.templates.delete(id);
+    }
+    /**
+     * Every parametrized page this user may open: model record pages, catalog
+     * items, templates registered by apps and any navigation link that carries
+     * placeholders of its own.
+     */
+    listTemplates(user) {
+        const templates = [];
+        const push = (template) => {
+            if (DESTRUCTIVE_PATH.test(template.template))
+                return;
+            if (template.accessRightsToken && !this.adminizer.accessRightsHelper.hasPermission(template.accessRightsToken, user))
+                return;
+            if (templates.some((existing) => existing.template === template.template || existing.id === template.id))
+                return;
+            templates.push(template);
+        };
+        for (const template of this.builtinTemplates(user))
+            push(template);
+        for (const template of this.templates.values())
+            push(template);
+        return templates;
+    }
+    /**
+     * Turns a template id (or its title) plus placeholder values into a real
+     * admin URL, rejecting templates this user may not open.
+     */
+    resolveTemplate(user, id, params = {}) {
+        const wanted = this.slug(id);
+        const available = this.listTemplates(user);
+        const template = available.find((candidate) => this.slug(candidate.id) === wanted)
+            ?? available.find((candidate) => this.slug(candidate.title) === wanted || this.slug(candidate.template) === wanted);
+        if (!template)
+            throw new Error(`Admin link template "${id}" is not available`);
+        return this.buildHref(template, params);
+    }
+    /** Fills the placeholders of a template with url-encoded values. */
+    buildHref(template, params = {}) {
+        return template.template.replace(/:([A-Za-z0-9_]+)/g, (_match, name) => {
+            const value = params[name];
+            if (value === undefined || value === null || value === '') {
+                throw new Error(`Admin link template "${template.id}" requires the "${name}" parameter`);
+            }
+            return encodeURIComponent(String(value));
+        });
+    }
+    /** True for paths that change data and therefore must never be navigated to. */
+    isDestructivePath(path) {
+        return DESTRUCTIVE_PATH.test(path);
+    }
+    /** Templates derived from the current configuration, catalogs and navigation. */
+    builtinTemplates(user) {
+        const prefix = (this.adminizer.config.routePrefix || '').replace(/\/+$/, '');
+        const templates = [];
+        const builtin = (id, title, path, accessRightsToken, description, section, params = []) => {
+            templates.push({
+                id, title, template: path, accessRightsToken, description, section, owner: 'host',
+                params: this.describeParams(path, params),
+            });
+        };
+        const recordId = [
+            { name: 'id', description: 'Identifier of the record, as returned when reading its data.' },
+        ];
+        for (const [model, config] of Object.entries(this.adminizer.config.models ?? {})) {
+            const title = typeof config === 'object' && config?.title ? config.title : model;
+            const section = typeof config === 'object' ? config?.navbar?.section : undefined;
+            builtin(`model-${model}-edit`, `${title}: open record`, `${prefix}/model/${model}/edit/:id`, `update-${model}-model`, `Open the edit page of a single ${title} record by its id.`, section, recordId);
+            builtin(`model-${model}-add`, `${title}: create record`, `${prefix}/model/${model}/add`, `create-${model}-model`, `Open the create form of ${title}.`, section);
+        }
+        for (const catalog of this.adminizer.catalogHandler.getAll()) {
+            if (!catalog?.slug)
+                continue;
+            builtin(`catalog-${catalog.slug}-item`, `${catalog.name || catalog.slug}: open item`, `${prefix}/catalog/${catalog.slug}/:id`, `catalog-${catalog.slug}`, `Open a single item of the ${catalog.name || catalog.slug} catalog by its id.`, undefined, recordId);
+        }
+        // Navigation links may carry placeholders themselves (app pages, custom
+        // tools). Such a link cannot be opened as-is, so it is a template.
+        const fromNavigation = (item, section) => {
+            const path = typeof item?.link === 'string' ? item.link : '';
+            if (path.startsWith('/') && /:[A-Za-z0-9_]+/.test(path) && item.title) {
+                templates.push({
+                    id: `link-${this.slug(String(item.id || item.title))}`,
+                    title: String(item.title),
+                    template: path,
+                    section: item.section || section,
+                    accessRightsToken: item.accessRightsToken || undefined,
+                    owner: 'host',
+                    params: this.describeParams(path),
+                });
+            }
+            for (const child of item?.actions ?? item?.subItems ?? [])
+                fromNavigation(child, item?.section || section);
+        };
+        for (const item of this.adminizer.menuHelper.getMenuItems(user))
+            fromNavigation(item, item.section);
+        for (const link of this.links.values())
+            fromNavigation(link, link.section);
+        return templates;
+    }
+    describeParams(path, described = []) {
+        const names = [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((match) => match[1]);
+        return [...new Set(names)].map((name) => ({
+            name,
+            description: described.find((param) => param.name === name)?.description,
+        }));
+    }
+    slug(value) {
+        return String(value).trim().toLowerCase().replace(/[\s_-]+/g, '-');
+    }
+}

package/lib/ai-assistant/AbstractAiModelService.d.ts

@@ -2,6 +2,8 @@ import { AiAgentConnectionStatus, AiAgentLimits, AiAgentModelOption, AiAgentPubl
 import { User } from '../../models/User.js';
 import type { Adminizer } from '../Adminizer.js';
 import { AbstractAiConversationHistoryService } from './AbstractAiConversationHistoryService.js';
+import type { AiAssistantAdminLink, AiAssistantNavigationTarget } from './AiAssistantUiMethodHandler.js';
+import type { AiAssistantAgentSkillDescriptor, AiAssistantSkillUser } from './AiAssistantAgentSkillHandler.js';
 export interface AiAgentChatCommand {
     /** Command name without the leading slash, e.g. `summarize`. */
     id: string;
@@ -61,7 +63,45 @@ export declare abstract class AbstractAiModelService {
     /** Commands available for autocomplete in the panel. */
     getChatCommands(): AiAgentChatCommand[];
     /** One declarative contract for the shared agent UI. */
-    getUiSchema(): AiAgentUiSchema;
+    getUiSchema(locale?: string): AiAgentUiSchema;
+    /**
+     * Browser capabilities available to a particular user.  Tool-capable
+     * services can turn these descriptors into their provider's tool format.
+     */
+    protected getUiMethods(user: User): import("./AiAssistantUiMethodHandler").AiAssistantUiMethod[];
+    /**
+     * Server-side implementation of the built-in `search-admin-links` skill.
+     * An OpenHarness/AI SDK adapter can return this value directly from its
+     * tool's `execute` callback.
+     */
+    protected searchAdminLinks(user: User, query?: string): AiAssistantAdminLink[];
+    /**
+     * Built-in and app-contributed server skills this user may call. Data
+     * skills are already scoped to that user's model permissions, so an agent
+     * exposing them can be offered to non-administrator accounts.
+     */
+    protected getAgentSkills(user: User): AiAssistantAgentSkillDescriptor[];
+    /**
+     * Executes an app-owned server skill after its permission check. The result
+     * is normalized to plain JSON: it becomes a tool result inside the agent's
+     * message history, which every later turn re-validates.
+     */
+    protected executeAgentSkill(id: string, input: Record<string, unknown>, user: User): Promise<unknown>;
+    /** Identity of the user an agent turn is running for. */
+    protected describeUser(user: User): AiAssistantSkillUser;
+    /**
+     * Opens an admin page for the user: either a concrete `href` or a link
+     * template plus `params` (a record page, a catalog item…). The target is
+     * validated against that user's permissions and the resolved URL is
+     * returned, so it can be reported back as the tool result.
+     */
+    protected openAdminLink(target: AiAssistantNavigationTarget, user: User, publish: AiAgentPublish): string;
+    /**
+     * Ask the shared panel to execute a registered browser method.  The
+     * registry and permission check stay server-side, so an LLM cannot invoke
+     * an arbitrary client event.
+     */
+    protected publishUiMethod(id: string, input: Record<string, unknown>, user: User, publish: AiAgentPublish): void;
     /**
      * Invoked by the agent transport for a registered `/command`. Returning
      * null intentionally lets an unhandled command flow into `streamReply`
@@ -104,7 +144,8 @@ export declare abstract class AbstractAiModelService {
     getLimits?(forceRefresh: boolean): Promise<AiAgentLimits | null>;
     /**
      * Panel copy for this service: title, welcome hint, composer placeholder,
-     * starter prompts and the setup hint of the connection loader.
+     * starter prompts and connection screens. The locale is resolved from the
+     * current admin user before this method is called.
      */
-    getUiHints?(): AiAgentUiHints;
+    getUiHints?(locale?: string): AiAgentUiHints;
 }

package/lib/ai-assistant/AbstractAiModelService.js

@@ -1,4 +1,5 @@
 import { InMemoryAiConversationHistoryService } from './AbstractAiConversationHistoryService.js';
+import { toJsonSafe } from './jsonSafe.js';
 /**
  * Base class for AI assistant models. App modules register access rights
  * and expose model metadata through this service.
@@ -70,9 +71,9 @@ export class AbstractAiModelService {
         return commands;
     }
     /** One declarative contract for the shared agent UI. */
-    getUiSchema() {
+    getUiSchema(locale) {
         return {
-            ...(this.getUiHints?.() ?? {}),
+            ...(this.getUiHints?.(locale) ?? {}),
             commands: this.getChatCommands(),
             panels: {
                 history: true,
@@ -81,6 +82,64 @@ export class AbstractAiModelService {
             },
         };
     }
+    /**
+     * Browser capabilities available to a particular user.  Tool-capable
+     * services can turn these descriptors into their provider's tool format.
+     */
+    getUiMethods(user) {
+        return this.adminizer.aiAssistantUiMethodHandler.getAvailable(user);
+    }
+    /**
+     * Server-side implementation of the built-in `search-admin-links` skill.
+     * An OpenHarness/AI SDK adapter can return this value directly from its
+     * tool's `execute` callback.
+     */
+    searchAdminLinks(user, query) {
+        return this.adminizer.aiAssistantUiMethodHandler.searchAdminLinks(user, query);
+    }
+    /**
+     * Built-in and app-contributed server skills this user may call. Data
+     * skills are already scoped to that user's model permissions, so an agent
+     * exposing them can be offered to non-administrator accounts.
+     */
+    getAgentSkills(user) {
+        return this.adminizer.aiAssistantAgentSkillHandler.getAvailable(user);
+    }
+    /**
+     * Executes an app-owned server skill after its permission check. The result
+     * is normalized to plain JSON: it becomes a tool result inside the agent's
+     * message history, which every later turn re-validates.
+     */
+    async executeAgentSkill(id, input, user) {
+        const result = await this.adminizer.aiAssistantAgentSkillHandler.execute(id, input, user);
+        return toJsonSafe(result) ?? null;
+    }
+    /** Identity of the user an agent turn is running for. */
+    describeUser(user) {
+        return this.adminizer.aiAssistantAgentSkillHandler.describeUser(user);
+    }
+    /**
+     * Opens an admin page for the user: either a concrete `href` or a link
+     * template plus `params` (a record page, a catalog item…). The target is
+     * validated against that user's permissions and the resolved URL is
+     * returned, so it can be reported back as the tool result.
+     */
+    openAdminLink(target, user, publish) {
+        const href = this.adminizer.aiAssistantUiMethodHandler.resolveNavigation(user, target);
+        this.publishUiMethod('navigate', { href }, user, publish);
+        return href;
+    }
+    /**
+     * Ask the shared panel to execute a registered browser method.  The
+     * registry and permission check stay server-side, so an LLM cannot invoke
+     * an arbitrary client event.
+     */
+    publishUiMethod(id, input, user, publish) {
+        const method = this.getUiMethods(user).find((candidate) => candidate.id === id);
+        if (!method)
+            throw new Error(`AI assistant UI method "${id}" is not available`);
+        publish({ type: 'ui.method', method: method.id, action: method.action, input });
+    }
     /**
      * Invoked by the agent transport for a registered `/command`. Returning
      * null intentionally lets an unhandled command flow into `streamReply`

package/lib/ai-assistant/AiAssistantAgentSkillHandler.d.ts

@@ -0,0 +1,58 @@
+import type { User } from '../../models/User.js';
+import type { Adminizer } from '../Adminizer.js';
+import type { AppRuntime } from '../app-manager/AdminizerApp.js';
+/** Identity of the admin user on whose behalf a skill runs. */
+export interface AiAssistantSkillUser {
+    id?: number;
+    login: string;
+    fullName?: string;
+    email?: string;
+    locale?: string;
+    isAdministrator: boolean;
+    groups: string[];
+}
+export interface AiAssistantAgentSkillContext {
+    user: User;
+    /** The same user as a plain descriptor, safe to return in a tool result. */
+    userIdentity: AiAssistantSkillUser;
+    runtime: AppRuntime;
+}
+/** A server-side tool made available to every compatible registered agent. */
+export interface AiAssistantAgentSkill {
+    id: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    accessRightsToken?: string;
+    /**
+     * Advertise the calling user inside the input schema. The agent then sees
+     * who it acts for and echoes it back; the value is always overwritten with
+     * the authenticated identity, so it cannot be used to impersonate.
+     */
+    requiresUser?: boolean;
+    /**
+     * Per-user refinement of what the agent is told about this skill, e.g. an
+     * enum of the models this particular user may read.
+     */
+    describe?(user: User, adminizer: Adminizer): {
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    } | undefined;
+    execute(input: Record<string, unknown>, context: AiAssistantAgentSkillContext): unknown | Promise<unknown>;
+}
+export type AiAssistantAgentSkillDescriptor = Omit<AiAssistantAgentSkill, 'execute' | 'describe'>;
+/** Input property that carries the calling user for `requiresUser` skills. */
+export declare const CURRENT_USER_PARAM = "currentUser";
+export declare class AiAssistantAgentSkillHandler {
+    private readonly adminizer;
+    private readonly skills;
+    constructor(adminizer: Adminizer);
+    add(skill: AiAssistantAgentSkill, owner?: string): void;
+    remove(id: string, owner?: string): boolean;
+    /** Skills this user may call, described with their permissions applied. */
+    getAvailable(user: User): AiAssistantAgentSkillDescriptor[];
+    execute(id: string, input: Record<string, unknown>, user: User): Promise<unknown>;
+    /** Plain, JSON-safe identity of an admin user. */
+    describeUser(user: User): AiAssistantSkillUser;
+    private isPermitted;
+    private describe;
+}

package/lib/ai-assistant/AiAssistantAgentSkillHandler.js

@@ -0,0 +1,87 @@
+import { buildBuiltinAgentSkills } from './builtinAgentSkills.js';
+/** Input property that carries the calling user for `requiresUser` skills. */
+export const CURRENT_USER_PARAM = 'currentUser';
+export class AiAssistantAgentSkillHandler {
+    adminizer;
+    skills = new Map();
+    constructor(adminizer) {
+        this.adminizer = adminizer;
+        // Built-in skills only read `adminizer` when they run, so registering
+        // them from the constructor is safe while Adminizer is still wiring up.
+        for (const skill of buildBuiltinAgentSkills(adminizer))
+            this.add(skill);
+    }
+    add(skill, owner = 'host') {
+        const id = skill.id.trim().toLowerCase();
+        if (!/^[a-z][a-z0-9_-]*$/.test(id))
+            throw new Error(`Invalid AI assistant skill id: ${skill.id}`);
+        if (!skill.description.trim())
+            throw new Error(`AI assistant skill "${id}" requires a description`);
+        if (this.skills.has(id))
+            throw new Error(`AI assistant skill "${id}" is already registered`);
+        this.skills.set(id, { ...skill, id, owner });
+    }
+    remove(id, owner) {
+        const skill = this.skills.get(id);
+        if (!skill || (owner && skill.owner !== owner))
+            return false;
+        return this.skills.delete(id);
+    }
+    /** Skills this user may call, described with their permissions applied. */
+    getAvailable(user) {
+        return [...this.skills.values()]
+            .filter((skill) => this.isPermitted(skill, user))
+            .map((skill) => this.describe(skill, user));
+    }
+    async execute(id, input, user) {
+        const skill = this.skills.get(id.trim().toLowerCase());
+        if (!skill || !this.isPermitted(skill, user)) {
+            throw new Error(`AI assistant skill "${id}" is not available`);
+        }
+        const userIdentity = this.describeUser(user);
+        // Whatever the model passed as the user is discarded: a skill acts for
+        // the authenticated admin user only.
+        const payload = skill.requiresUser
+            ? { ...input, [CURRENT_USER_PARAM]: userIdentity.login }
+            : input;
+        return skill.execute(payload, {
+            user,
+            userIdentity,
+            runtime: this.adminizer.appManager.createRuntime(skill.owner),
+        });
+    }
+    /** Plain, JSON-safe identity of an admin user. */
+    describeUser(user) {
+        return {
+            id: user.id,
+            login: user.login,
+            fullName: user.fullName || undefined,
+            email: user.email || undefined,
+            locale: user.locale || undefined,
+            isAdministrator: Boolean(user.isAdministrator),
+            groups: (user.groups ?? []).map((group) => group?.name).filter(Boolean),
+        };
+    }
+    isPermitted(skill, user) {
+        return !skill.accessRightsToken || this.adminizer.accessRightsHelper.hasPermission(skill.accessRightsToken, user);
+    }
+    describe(skill, user) {
+        const refinement = skill.describe?.(user, this.adminizer) ?? {};
+        const { execute: _execute, describe: _describe, owner: _owner, ...rest } = skill;
+        const inputSchema = { ...(refinement.inputSchema ?? skill.inputSchema) };
+        if (skill.requiresUser) {
+            const identity = this.describeUser(user);
+            const properties = { ...(inputSchema.properties ?? {}) };
+            properties[CURRENT_USER_PARAM] = {
+                type: 'string',
+                enum: [identity.login],
+                description: `Login of the admin user this conversation belongs to (id ${identity.id}`
+                    + `${identity.fullName ? `, ${identity.fullName}` : ''}). Always pass "${identity.login}".`,
+            };
+            const required = new Set([...(inputSchema.required ?? []), CURRENT_USER_PARAM]);
+            inputSchema.properties = properties;
+            inputSchema.required = [...required];
+        }
+        return { ...rest, description: refinement.description ?? skill.description, inputSchema };
+    }
+}

package/lib/ai-assistant/AiAssistantUiMethodHandler.d.ts

@@ -0,0 +1,60 @@
+import type { User } from '../../models/User.js';
+import type { Adminizer } from '../Adminizer.js';
+import type { AdminLinkTemplateParam } from '../admin-links/AdminLinkHandler.js';
+export interface AiAssistantAdminLink {
+    id: string;
+    title: string;
+    /** Concrete page, ready for `navigate`. Absent for templates. */
+    link?: string;
+    /** Parametrized page: pass `template` plus `params` to `navigate`. */
+    template?: string;
+    /** Placeholders that must be filled to open a template. */
+    params?: AdminLinkTemplateParam[];
+    description?: string;
+    section?: string;
+}
+/**
+ * A browser capability an AI service may expose as a tool.  The agent emits
+ * `ui.method` with this id; the assistant panel performs the browser action.
+ */
+export interface AiAssistantUiMethod {
+    id: string;
+    title: string;
+    description: string;
+    /** JSON Schema consumed by tool-capable model services. */
+    inputSchema: Record<string, unknown>;
+    /** Built-in browser executor understood by the shared assistant panel. */
+    action: 'navigate' | 'search-admin-links' | string;
+    accessRightsToken?: string;
+}
+/** What the agent may ask to open: a concrete link or a template plus values. */
+export interface AiAssistantNavigationTarget {
+    href?: string;
+    template?: string;
+    params?: Record<string, unknown>;
+}
+export declare class AiAssistantUiMethodHandler {
+    private readonly adminizer;
+    private readonly methods;
+    private readonly owners;
+    constructor(adminizer: Adminizer);
+    register(method: AiAssistantUiMethod, owner?: string): void;
+    unregister(id: string, owner?: string): void;
+    getAvailable(user: User): AiAssistantUiMethod[];
+    /**
+     * Search exactly the navigation a user can open.  This intentionally uses
+     * MenuHelper rather than client-side markup, therefore a tool result is
+     * permission-safe and works when the assistant panel is not visible.
+     *
+     * Parametrized pages are returned as templates, so a record page is
+     * reachable even though its URL only exists once the id is known.
+     */
+    searchAdminLinks(user: User, query?: string): AiAssistantAdminLink[];
+    /**
+     * Validates what an agent asked to open and returns the concrete admin URL.
+     * Templates are resolved against this user's own permissions, so the LLM
+     * can only reach pages that user could reach by clicking.
+     */
+    resolveNavigation(user: User, target: AiAssistantNavigationTarget): string;
+    private slug;
+}