adminizer 5.0.0-build.11 → 5.0.0-build.12

package/helpers/navigationAccessHelper.d.ts

@@ -0,0 +1,13 @@
+import type { HrefConfig } from '../interfaces/adminpanelConfig.js';
+import type { Adminizer } from '../lib/Adminizer.js';
+import type { User } from '../models/User.js';
+import type { MenuItem } from './menuHelper.js';
+/** Drops the sub-items this user may not open, recursively. */
+export declare function filterAccessibleHrefItems(adminizer: Adminizer, user: User, items: HrefConfig[]): HrefConfig[];
+/**
+ * The navigation menu a user may actually open: configured models, additional
+ * links and app-contributed pages, filtered with the very same rules the
+ * sidebar uses. Titles are left untranslated, so callers that need i18n (the
+ * Inertia page props) translate on top of this.
+ */
+export declare function listAccessibleMenuItems(adminizer: Adminizer, user: User): MenuItem[];

package/helpers/navigationAccessHelper.js

@@ -0,0 +1,40 @@
+/** Drops the sub-items this user may not open, recursively. */
+export function filterAccessibleHrefItems(adminizer, user, items) {
+    return items
+        .filter((item) => !item.accessRightsToken || adminizer.accessRightsHelper.hasPermission(item.accessRightsToken, user))
+        .map((item) => ({
+        ...item,
+        subItems: item.subItems ? filterAccessibleHrefItems(adminizer, user, item.subItems) : item.subItems,
+    }));
+}
+/**
+ * The navigation menu a user may actually open: configured models, additional
+ * links and app-contributed pages, filtered with the very same rules the
+ * sidebar uses. Titles are left untranslated, so callers that need i18n (the
+ * Inertia page props) translate on top of this.
+ */
+export function listAccessibleMenuItems(adminizer, user) {
+    const menu = [];
+    for (const menuItem of adminizer.menuHelper.getMenuItems(user)) {
+        const actions = filterAccessibleHrefItems(adminizer, user, menuItem.actions ?? []);
+        const tokens = actions.map((item) => item.accessRightsToken).filter(Boolean);
+        if (menuItem.accessRightsToken)
+            tokens.push(menuItem.accessRightsToken);
+        if (adminizer.accessRightsHelper.enoughPermissions(tokens, user)) {
+            menu.push({ ...menuItem, actions });
+        }
+    }
+    for (const link of adminizer.adminLinkHandler.list(user)) {
+        menu.push({
+            id: link.id,
+            link: link.link,
+            title: link.title,
+            type: link.type === 'blank' ? 'blank' : 'self',
+            actions: null,
+            icon: null,
+            accessRightsToken: link.accessRightsToken ?? null,
+            section: link.section || 'Platform',
+        });
+    }
+    return menu;
+}

package/index.d.ts

@@ -46,6 +46,12 @@ export * from "./lib/ai-assistant/AbstractAiModelService.js";
 export * from "./lib/ai-assistant/AbstractAiConversationHistoryService.js";
 export * from "./lib/ai-assistant/AiAssistantHandler.js";
 export * from "./lib/ai-assistant/AiAgentRunManager.js";
+export * from "./lib/ai-assistant/jsonSafe.js";
+export * from "./lib/ai-assistant/AiAssistantUiMethodHandler.js";
+export * from "./lib/ai-assistant/AiAssistantAgentSkillHandler.js";
+export * from "./lib/admin-links/AdminLinkHandler.js";
+export * from "./helpers/modelResourceHelper.js";
+export * from "./helpers/navigationAccessHelper.js";
 export * from "./lib/DataAccessor.js";
 export * from "./lib/history-actions/AbstractHistoryAdapter.js";
 export * from "./lib/filters/CustomFilterHandler.js";

package/index.js

@@ -46,6 +46,12 @@ export * from "./lib/ai-assistant/AbstractAiModelService.js";
 export * from "./lib/ai-assistant/AbstractAiConversationHistoryService.js";
 export * from "./lib/ai-assistant/AiAssistantHandler.js";
 export * from "./lib/ai-assistant/AiAgentRunManager.js";
+export * from "./lib/ai-assistant/jsonSafe.js";
+export * from "./lib/ai-assistant/AiAssistantUiMethodHandler.js";
+export * from "./lib/ai-assistant/AiAssistantAgentSkillHandler.js";
+export * from "./lib/admin-links/AdminLinkHandler.js";
+export * from "./helpers/modelResourceHelper.js";
+export * from "./helpers/navigationAccessHelper.js";
 export * from "./lib/DataAccessor.js";
 export * from "./lib/history-actions/AbstractHistoryAdapter.js";
 export * from "./lib/filters/CustomFilterHandler.js";

package/interfaces/types.d.ts

@@ -123,6 +123,29 @@ export interface AiAgentConnectionStatus {
     expiresAt?: string | null;
     [key: string]: unknown;
 }
+/** States for which an agent can describe its connection screen. */
+export type AiAgentConnectionState = Exclude<AiAgentConnectionStatus['state'], 'ready'>;
+/**
+ * Declarative connection screen supplied by an agent service. The shared panel
+ * owns rendering, while the agent owns its copy, CTA and which status details
+ * are useful to expose.
+ */
+export interface AiAgentConnectionScreen {
+    title?: string;
+    description?: string;
+    icon?: 'spinner' | 'bot' | 'error';
+    action?: {
+        label: string;
+        href: string;
+    };
+    /** Status values the agent wants to render on this screen. */
+    details?: Array<{
+        field: string;
+        label?: string;
+        format?: 'text' | 'local-time';
+        tone?: 'muted' | 'error';
+    }>;
+}
 /** Normalized budget / rate limits of the provider key, when it exposes them. */
 export interface AiAgentLimits {
     provider: string;
@@ -144,9 +167,8 @@ export interface AiAgentLimits {
     [key: string]: unknown;
 }
 /**
- * Copy the panel shows instead of its neutral defaults. Strings go through the
- * panel's own dictionary first, so English source strings it already knows are
- * still translated.
+ * Copy the panel shows instead of its neutral defaults. `getUiHints(locale)`
+ * receives the admin user's locale, so agents can return localized copy.
  */
 export interface AiAgentUiHints {
     title?: string;
@@ -157,14 +179,29 @@ export interface AiAgentUiHints {
     setupSetting?: string;
     /** Where to fill it in; rendered as a button on the connection loader. */
     setupUrl?: string;
+    /**
+     * Per-state pages rendered while this agent is not ready. `default` is
+     * used for any state without its own screen.
+     */
+    connectionScreens?: Partial<Record<AiAgentConnectionState | 'default', AiAgentConnectionScreen>>;
     [key: string]: unknown;
 }
+/** A browser-side capability which an agent may call through `ui.method`. */
+export interface AiAgentUiMethod {
+    id: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    action: string;
+    accessRightsToken?: string;
+}
 /** Declarative UI contract consumed by the shared assistant panel. */
 export interface AiAgentUiSchema extends AiAgentUiHints {
     commands: Array<{
         id: string;
         description?: string;
     }>;
+    uiMethods?: AiAgentUiMethod[];
     panels: {
         history: boolean;
         models: boolean;

package/lib/Adminizer.d.ts

@@ -27,6 +27,9 @@ import { ControllerHandler } from "./app-manager/ControllerHandler.js";
 import { AssetHandler } from "./app-manager/AssetHandler.js";
 import { ConfigLayerHandler } from "./app-manager/ConfigLayerHandler.js";
 import { AccessRightsHandler } from "./access-rights/AccessRightsHandler.js";
+import { AiAssistantUiMethodHandler } from './ai-assistant/AiAssistantUiMethodHandler.js';
+import { AdminLinkHandler } from './admin-links/AdminLinkHandler.js';
+import { AiAssistantAgentSkillHandler } from './ai-assistant/AiAssistantAgentSkillHandler.js';
 export declare function createAdminizerLogger(): winston.Logger;
 export interface EmitAsyncOptions {
     /**
@@ -54,6 +57,9 @@ export declare class Adminizer {
     notificationHandler: NotificationHandler;
     historyHandler: HistoryHandler;
     private _aiAssistantHandler?;
+    aiAssistantUiMethodHandler: AiAssistantUiMethodHandler;
+    adminLinkHandler: AdminLinkHandler;
+    aiAssistantAgentSkillHandler: AiAssistantAgentSkillHandler;
     modelHandler: ModelHandler;
     widgetHandler: WidgetHandler;
     customFilterHandler: CustomFilterHandler;

package/lib/Adminizer.js

@@ -43,6 +43,9 @@ import { ControllerHandler } from "./app-manager/ControllerHandler.js";
 import { AssetHandler } from "./app-manager/AssetHandler.js";
 import { ConfigLayerHandler } from "./app-manager/ConfigLayerHandler.js";
 import { AccessRightsHandler } from "./access-rights/AccessRightsHandler.js";
+import { AiAssistantUiMethodHandler } from './ai-assistant/AiAssistantUiMethodHandler.js';
+import { AdminLinkHandler } from './admin-links/AdminLinkHandler.js';
+import { AiAssistantAgentSkillHandler } from './ai-assistant/AiAssistantAgentSkillHandler.js';
 const logFilePath = "logs/app.log";
 function ensureLogDirectory(filePath) {
     const logDirectory = path.dirname(filePath);
@@ -109,6 +112,9 @@ export class Adminizer {
     notificationHandler;
     historyHandler;
     _aiAssistantHandler;
+    aiAssistantUiMethodHandler;
+    adminLinkHandler;
+    aiAssistantAgentSkillHandler;
     modelHandler;
     widgetHandler;
     customFilterHandler;
@@ -141,6 +147,9 @@ export class Adminizer {
         this.catalogTemplateComponentHandler = new CatalogTemplateComponentHandler();
         this.mediaManagerHandler = new MediaManagerHandler();
         this.feedbackHandler = new FeedbackHandler(this);
+        this.aiAssistantUiMethodHandler = new AiAssistantUiMethodHandler(this);
+        this.adminLinkHandler = new AdminLinkHandler(this);
+        this.aiAssistantAgentSkillHandler = new AiAssistantAgentSkillHandler(this);
         this.controllerHandler = new ControllerHandler(this);
         this.assetHandler = new AssetHandler(this);
         this.configLayerHandler = new ConfigLayerHandler(this);

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;
+}