adminizer 5.0.0-build.8 → 5.1.0-build.24

package/lib/admin-links/AdminLinkHandler.js

@@ -0,0 +1,183 @@
+/** 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);
+    }
+    async list(user, type) {
+        const wanted = type ? this.slug(type) : null;
+        const accessible = [];
+        for (const link of this.links.values()) {
+            if (wanted && this.slug(link.type) !== wanted)
+                continue;
+            if (link.accessRightsToken && !await this.adminizer.accessRightsHelper.hasPermission(link.accessRightsToken, user))
+                continue;
+            accessible.push(link);
+        }
+        return accessible;
+    }
+    async resolve(user, type, name) {
+        const wanted = this.slug(name);
+        return (await 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.
+     */
+    async listTemplates(user) {
+        const templates = [];
+        const push = async (template) => {
+            if (DESTRUCTIVE_PATH.test(template.template))
+                return;
+            if (template.accessRightsToken && !await 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))
+            await push(template);
+        for (const template of this.templates.values())
+            await 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.
+     */
+    async resolveTemplate(user, id, params = {}) {
+        const wanted = this.slug(id);
+        const available = await 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/AbstractAiConversationHistoryService.d.ts

@@ -0,0 +1,39 @@
+import type { Adminizer } from '../Adminizer.js';
+import type { AbstractAiModelService } from './AbstractAiModelService.js';
+import type { User } from '../../models/User.js';
+export interface AiConversation {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: Array<Record<string, unknown>>;
+}
+/**
+ * Storage contract for an agent's dialogs. Applications can extend this class
+ * to persist conversations in their own database instead of process memory.
+ */
+export declare abstract class AbstractAiConversationHistoryService {
+    protected agent: AbstractAiModelService;
+    protected adminizer: Adminizer;
+    initialize(agent: AbstractAiModelService, adminizer: Adminizer): void;
+    abstract list(user: User): AiConversation[];
+    abstract getActive(user: User): AiConversation;
+    abstract create(user: User, title?: string): AiConversation;
+    abstract select(user: User, conversationId: string): AiConversation | undefined;
+    abstract remove(user: User, conversationId: string): boolean;
+    abstract saveActive(user: User, messages: Array<Record<string, unknown>>, title?: string): AiConversation;
+}
+/** Default storage used when an agent does not provide a database-backed one. */
+export declare class InMemoryAiConversationHistoryService extends AbstractAiConversationHistoryService {
+    private readonly conversations;
+    private readonly activeConversationIds;
+    list(user: User): AiConversation[];
+    getActive(user: User): AiConversation;
+    create(user: User, title?: string): AiConversation;
+    select(user: User, conversationId: string): AiConversation | undefined;
+    remove(user: User, conversationId: string): boolean;
+    saveActive(user: User, messages: Array<Record<string, unknown>>, title?: string): AiConversation;
+    private getConversations;
+    private getKey;
+    private findFirstUserText;
+}

package/lib/ai-assistant/AbstractAiConversationHistoryService.js

@@ -0,0 +1,98 @@
+/**
+ * Storage contract for an agent's dialogs. Applications can extend this class
+ * to persist conversations in their own database instead of process memory.
+ */
+export class AbstractAiConversationHistoryService {
+    agent;
+    adminizer;
+    initialize(agent, adminizer) {
+        this.agent = agent;
+        this.adminizer = adminizer;
+    }
+}
+/** Default storage used when an agent does not provide a database-backed one. */
+export class InMemoryAiConversationHistoryService extends AbstractAiConversationHistoryService {
+    conversations = new Map();
+    activeConversationIds = new Map();
+    list(user) {
+        return [...this.getConversations(user)]
+            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    }
+    getActive(user) {
+        const key = this.getKey(user);
+        const conversations = this.getConversations(user);
+        const activeId = this.activeConversationIds.get(key);
+        const active = conversations.find((conversation) => conversation.id === activeId);
+        if (active)
+            return active;
+        const conversation = this.create(user);
+        this.activeConversationIds.set(key, conversation.id);
+        return conversation;
+    }
+    create(user, title = 'New conversation') {
+        const now = new Date().toISOString();
+        const conversation = {
+            id: `conversation-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
+            title,
+            createdAt: now,
+            updatedAt: now,
+            messages: [],
+        };
+        this.getConversations(user).push(conversation);
+        this.activeConversationIds.set(this.getKey(user), conversation.id);
+        return conversation;
+    }
+    select(user, conversationId) {
+        const conversation = this.getConversations(user).find((item) => item.id === conversationId);
+        if (conversation)
+            this.activeConversationIds.set(this.getKey(user), conversation.id);
+        return conversation;
+    }
+    remove(user, conversationId) {
+        const conversations = this.getConversations(user);
+        const index = conversations.findIndex((conversation) => conversation.id === conversationId);
+        if (index < 0)
+            return false;
+        conversations.splice(index, 1);
+        if (this.activeConversationIds.get(this.getKey(user)) === conversationId) {
+            this.activeConversationIds.delete(this.getKey(user));
+        }
+        return true;
+    }
+    saveActive(user, messages, title) {
+        const conversation = this.getActive(user);
+        conversation.messages = messages;
+        conversation.updatedAt = new Date().toISOString();
+        if (title)
+            conversation.title = title;
+        else if (conversation.title === 'New conversation') {
+            const firstText = this.findFirstUserText(messages);
+            if (firstText)
+                conversation.title = firstText.slice(0, 80);
+        }
+        return conversation;
+    }
+    getConversations(user) {
+        const key = this.getKey(user);
+        let conversations = this.conversations.get(key);
+        if (!conversations) {
+            conversations = [];
+            this.conversations.set(key, conversations);
+        }
+        return conversations;
+    }
+    getKey(user) {
+        return `${user.id}:${this.agent.id}`;
+    }
+    findFirstUserText(messages) {
+        const message = messages.find((item) => item.role === 'user');
+        const content = message?.content;
+        if (typeof content === 'string')
+            return content.trim();
+        if (Array.isArray(content)) {
+            const text = content.find((part) => part && typeof part === 'object' && part.type === 'text');
+            return typeof text?.text === 'string' ? text.text.trim() : undefined;
+        }
+        return undefined;
+    }
+}

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

@@ -1,14 +1,151 @@
-import { AiAssistantMessage, AiAssistantModelInfo } from '../../interfaces/types.js';
+import { AiAgentConnectionStatus, AiAgentLimits, AiAgentModelOption, AiAgentPublish, AiAgentSavedFile, AiAgentSessionMeta, AiAgentUiHints, AiAgentUiSchema, AiAgentUploadedFile, AiAssistantMessage, AiAssistantModelInfo } from '../../interfaces/types.js';
 import { User } from '../../models/User.js';
+import type { Adminizer } from '../Adminizer.js';
+import { AbstractAiConversationHistoryService } from './AbstractAiConversationHistoryService.js';
+import type { AiAssistantAdminLink, AiAssistantNavigationTarget, AiAssistantUiMethod } from './AiAssistantUiMethodHandler.js';
+import type { AiAssistantAgentSkillDescriptor, AiAssistantSkillUser } from './AiAssistantAgentSkillHandler.js';
+export interface AiAgentChatCommand {
+    /** Command name without the leading slash, e.g. `summarize`. */
+    id: string;
+    /** Short explanation rendered in the command picker. */
+    description?: string;
+}
+export interface AiAgentChatCommandContext {
+    command: AiAgentChatCommand;
+    arguments: string;
+    input: string | Array<Record<string, unknown>>;
+    user: User;
+    publish: AiAgentPublish;
+}
+export interface AiAgentChatCommandResult {
+    /** Text rendered as the command response and stored in the dialog. */
+    text?: string;
+    /** Set false for ephemeral commands that must not enter agent history. */
+    persist?: boolean;
+}
+export type AiAgentChatCommandHandler = (context: AiAgentChatCommandContext) => Promise<AiAgentChatCommandResult | void> | AiAgentChatCommandResult | void;
 /**
  * Base class for AI assistant models. App modules register access rights
  * and expose model metadata through this service.
+ *
+ * Two levels of capability:
+ *
+ * 1. `generateReply` — required. A plain request/response chat model; the
+ *    assistant panel runs it through the same streaming transport and shows
+ *    the answer as a single text part.
+ * 2. The optional agent members below. A service that implements `streamReply`
+ *    is driven as a real agent: tool calls, reasoning, attachments and a
+ *    server-side per-user session (history, compaction, model switching) are
+ *    surfaced by the panel. Whatever the service does not implement is simply
+ *    not rendered, so partial implementations are fine.
  */
 export declare abstract class AbstractAiModelService {
     readonly id: string;
     readonly name: string;
     readonly description?: string;
-    protected constructor(metadata: AiAssistantModelInfo);
+    /**
+     * Set when the model is registered. Agent implementations need it to read
+     * the panel config, the model registry and the user's permissions.
+     */
+    protected adminizer: Adminizer;
+    readonly conversationHistory: AbstractAiConversationHistoryService;
+    private readonly chatCommands;
+    protected constructor(metadata: AiAssistantModelInfo, conversationHistory?: AbstractAiConversationHistoryService);
+    /** Called by AiAssistantHandler on registration; not part of the model API. */
+    attachAdminizer(adminizer: Adminizer): void;
     getMetadata(): AiAssistantModelInfo;
+    /**
+     * Registers a slash command owned by this agent. The panel only displays
+     * it and sends its raw `/command arguments` text back to this service;
+     * command handling never lives in the browser.
+     */
+    registerChatCommand(command: AiAgentChatCommand, handler?: AiAgentChatCommandHandler): void;
+    /** Commands available for autocomplete in the panel. */
+    getChatCommands(): AiAgentChatCommand[];
+    /** One declarative contract for the shared agent UI. */
+    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): Promise<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): Promise<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): Promise<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): Promise<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): Promise<void>;
+    /**
+     * Invoked by the agent transport for a registered `/command`. Returning
+     * null intentionally lets an unhandled command flow into `streamReply`
+     * or `generateReply` as regular agent input. A handler should return text
+     * instead of publishing a plain text frame itself, so its response can be
+     * persisted in the active conversation.
+     */
+    executeChatCommand(prompt: string, input: string | Array<Record<string, unknown>>, user: User, publish: AiAgentPublish): Promise<AiAgentChatCommandResult | null>;
     abstract generateReply(prompt: string, history: AiAssistantMessage[], user: User): Promise<string>;
+    /** True when the service streams runs itself instead of answering in one shot. */
+    isStreamingAgent(): boolean;
+    /**
+     * Run one turn and report progress through `publish`. `input` is either the
+     * plain prompt or an ai-sdk style ModelMessage[] when files are attached.
+     * The closing `done` frame is emitted by the run manager, not by the service.
+     */
+    streamReply?(input: string | Array<Record<string, unknown>>, user: User, publish: AiAgentPublish): Promise<void>;
+    /** Current model, context usage and turn count of this user's session. */
+    getSessionMeta?(user: User): AiAgentSessionMeta;
+    /** Session history as ai-sdk ModelMessage[]; the panel rebuilds the thread from it. */
+    getSessionHistory?(user: User): Array<Record<string, unknown>>;
+    /** Restores a stored dialog when the user switches conversations. */
+    restoreSessionHistory?(user: User, messages: Array<Record<string, unknown>>): Promise<void> | void;
+    /** Drop the session. Returns whether there was anything to drop. */
+    resetSession?(user: User): boolean;
+    /** Summarize the session to free context. Returns e.g. tokensBefore/tokensAfter. */
+    compactSession?(user: User): Promise<Record<string, unknown>>;
+    /** LLMs the user may switch between inside this service. */
+    getModelChoices?(): Promise<AiAgentModelOption[]>;
+    /** Switch the session model. Returns whether the model changed. */
+    setCurrentModel?(user: User, model: string): Promise<boolean>;
+    /** Persist uploads before the turn, so tools can refer to them by id. */
+    saveUploadedFiles?(user: User, files: AiAgentUploadedFile[]): Promise<AiAgentSavedFile[]>;
+    /**
+     * Provisioning state. Omit when the service is always usable; when present
+     * and not `ready`, the panel shows a loader instead of the composer.
+     */
+    getConnectionStatus?(): Promise<AiAgentConnectionStatus> | AiAgentConnectionStatus;
+    /** Budget / rate limits of the provider key, when the provider exposes them. */
+    getLimits?(forceRefresh: boolean): Promise<AiAgentLimits | null>;
+    /**
+     * Panel copy for this service: title, welcome hint, composer placeholder,
+     * starter prompts and connection screens. The locale is resolved from the
+     * current admin user before this method is called.
+     */
+    getUiHints?(locale?: string): AiAgentUiHints;
 }

package/lib/ai-assistant/AbstractAiModelService.js

@@ -1,15 +1,41 @@
+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.
+ *
+ * Two levels of capability:
+ *
+ * 1. `generateReply` — required. A plain request/response chat model; the
+ *    assistant panel runs it through the same streaming transport and shows
+ *    the answer as a single text part.
+ * 2. The optional agent members below. A service that implements `streamReply`
+ *    is driven as a real agent: tool calls, reasoning, attachments and a
+ *    server-side per-user session (history, compaction, model switching) are
+ *    surfaced by the panel. Whatever the service does not implement is simply
+ *    not rendered, so partial implementations are fine.
  */
 export class AbstractAiModelService {
     id;
     name;
     description;
-    constructor(metadata) {
+    /**
+     * Set when the model is registered. Agent implementations need it to read
+     * the panel config, the model registry and the user's permissions.
+     */
+    adminizer;
+    conversationHistory;
+    chatCommands = new Map();
+    constructor(metadata, conversationHistory = new InMemoryAiConversationHistoryService()) {
         this.id = metadata.id;
         this.name = metadata.name;
         this.description = metadata.description;
+        this.conversationHistory = conversationHistory;
+    }
+    /** Called by AiAssistantHandler on registration; not part of the model API. */
+    attachAdminizer(adminizer) {
+        this.adminizer = adminizer;
+        this.conversationHistory.initialize(this, adminizer);
     }
     getMetadata() {
         return {
@@ -18,4 +44,131 @@ export class AbstractAiModelService {
             description: this.description,
         };
     }
+    /**
+     * Registers a slash command owned by this agent. The panel only displays
+     * it and sends its raw `/command arguments` text back to this service;
+     * command handling never lives in the browser.
+     */
+    registerChatCommand(command, handler) {
+        const id = command.id.trim().replace(/^\/+/, '').toLowerCase();
+        if (!/^[a-z][a-z0-9_-]*$/.test(id)) {
+            throw new Error(`Invalid AI agent command id: ${command.id}`);
+        }
+        this.chatCommands.set(id, {
+            command: { id, description: command.description?.trim() || undefined },
+            handler,
+        });
+    }
+    /** Commands available for autocomplete in the panel. */
+    getChatCommands() {
+        const commands = [...this.chatCommands.values()].map(({ command }) => ({ ...command }));
+        if (typeof this.compactSession === 'function' && !this.chatCommands.has('compact')) {
+            commands.unshift({
+                id: 'compact',
+                description: 'Prune or summarize older messages to free context.',
+            });
+        }
+        return commands;
+    }
+    /** One declarative contract for the shared agent UI. */
+    getUiSchema(locale) {
+        return {
+            ...(this.getUiHints?.(locale) ?? {}),
+            commands: this.getChatCommands(),
+            panels: {
+                history: true,
+                models: typeof this.getModelChoices === 'function' && typeof this.setCurrentModel === 'function',
+                limits: typeof this.getLimits === 'function',
+            },
+        };
+    }
+    /**
+     * 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.
+     */
+    async openAdminLink(target, user, publish) {
+        const href = await this.adminizer.aiAssistantUiMethodHandler.resolveNavigation(user, target);
+        await 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.
+     */
+    async publishUiMethod(id, input, user, publish) {
+        const method = (await 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`
+     * or `generateReply` as regular agent input. A handler should return text
+     * instead of publishing a plain text frame itself, so its response can be
+     * persisted in the active conversation.
+     */
+    async executeChatCommand(prompt, input, user, publish) {
+        const match = /^\/([a-z][a-z0-9_-]*)(?:\s+([\s\S]*))?$/i.exec(prompt.trim());
+        if (!match)
+            return null;
+        const entry = this.chatCommands.get(match[1].toLowerCase());
+        if (entry?.handler) {
+            const result = await entry.handler({ command: entry.command, arguments: match[2] ?? '', input, user, publish });
+            return { persist: true, ...result };
+        }
+        if (match[1].toLowerCase() !== 'compact' || typeof this.compactSession !== 'function')
+            return null;
+        const result = await this.compactSession(user);
+        const compacted = result.compacted === true;
+        const before = Number(result.tokensBefore ?? 0);
+        const after = Number(result.tokensAfter ?? 0);
+        const text = compacted
+            ? `Context compacted${before > 0 ? `: ${before} → ${after} tokens.` : '.'}`
+            : 'Nothing to compact yet.';
+        return { text, persist: true };
+    }
+    /** True when the service streams runs itself instead of answering in one shot. */
+    isStreamingAgent() {
+        return typeof this.streamReply === 'function';
+    }
 }