adminizer 5.0.0-build.2 → 5.0.0-build.21

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

@@ -1,14 +1,151 @@
-import { AiAssistantMessage, AiAssistantModelInfo } from '../../interfaces/types';
-import { User } from '../../models/User';
+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 } 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): 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`
+     * 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.
+     */
+    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`
+     * 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';
+    }
 }

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

@@ -0,0 +1,35 @@
+import { AiAgentStreamEvent } from '../../interfaces/types.js';
+interface AgentRun {
+    id: string;
+    userId: number;
+    modelId: string;
+    createdAt: number;
+    events: AiAgentStreamEvent[];
+    clients: Set<ResType>;
+    done: boolean;
+}
+/**
+ * Buffered SSE transport for agent runs.
+ *
+ * A run is started by a POST that returns immediately (so the browser can open
+ * the stream) and then writes its events here. Every event is stored with its
+ * index and used as the SSE event id, which lets EventSource resume through
+ * `Last-Event-ID` after a reconnect without replaying what the client already
+ * processed.
+ */
+export declare class AiAgentRunManager {
+    private readonly runs;
+    create(userId: number, modelId: string): AgentRun;
+    /** Only the owner may read a run. */
+    get(runId: string, userId: number): AgentRun | undefined;
+    publish(run: AgentRun, event: AiAgentStreamEvent): void;
+    /** Marks the run finished and flushes the closing frame to every client. */
+    finish(run: AgentRun, event: AiAgentStreamEvent): void;
+    /** Streams a run to one client: replays what it missed, then follows live. */
+    subscribe(run: AgentRun, req: ReqType, res: ResType): void;
+    private write;
+    /** SSE payloads must be JSON-safe and bounded. */
+    private sanitize;
+    private cleanup;
+}
+export type { AgentRun };

package/lib/ai-assistant/AiAgentRunManager.js

@@ -0,0 +1,109 @@
+/** Runs are kept only long enough for a reconnecting EventSource to catch up. */
+const MAX_RUN_AGE_MS = 10 * 60 * 1000;
+/** Hard cap per SSE frame, so a chatty tool result cannot blow up memory. */
+const MAX_EVENT_JSON_CHARS = 64 * 1024;
+/**
+ * Buffered SSE transport for agent runs.
+ *
+ * A run is started by a POST that returns immediately (so the browser can open
+ * the stream) and then writes its events here. Every event is stored with its
+ * index and used as the SSE event id, which lets EventSource resume through
+ * `Last-Event-ID` after a reconnect without replaying what the client already
+ * processed.
+ */
+export class AiAgentRunManager {
+    runs = new Map();
+    create(userId, modelId) {
+        this.cleanup();
+        const id = `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+        const run = {
+            id,
+            userId,
+            modelId,
+            createdAt: Date.now(),
+            events: [],
+            clients: new Set(),
+            done: false,
+        };
+        this.runs.set(id, run);
+        return run;
+    }
+    /** Only the owner may read a run. */
+    get(runId, userId) {
+        const run = this.runs.get(runId);
+        return run && run.userId === userId ? run : undefined;
+    }
+    publish(run, event) {
+        const safe = this.sanitize(event);
+        const index = run.events.push(safe) - 1;
+        for (const client of run.clients)
+            this.write(client, 'agent', safe, index);
+    }
+    /** Marks the run finished and flushes the closing frame to every client. */
+    finish(run, event) {
+        run.done = true;
+        this.publish(run, event);
+        for (const client of run.clients)
+            client.end();
+        run.clients.clear();
+    }
+    /** Streams a run to one client: replays what it missed, then follows live. */
+    subscribe(run, req, res) {
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache, no-transform');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no');
+        res.flushHeaders?.();
+        res.write('retry: 3000\n\n');
+        this.write(res, 'connected', { runId: run.id });
+        const lastEventId = Number(req.headers['last-event-id']);
+        const start = Number.isFinite(lastEventId) ? lastEventId + 1 : 0;
+        for (let i = start; i < run.events.length; i++) {
+            this.write(res, 'agent', run.events[i], i);
+        }
+        if (run.done) {
+            res.end();
+            return;
+        }
+        run.clients.add(res);
+        req.on('close', () => run.clients.delete(res));
+    }
+    write(res, event, data, id) {
+        if (id !== undefined)
+            res.write(`id: ${id}\n`);
+        res.write(`event: ${event}\n`);
+        res.write(`data: ${JSON.stringify(data)}\n\n`);
+    }
+    /** SSE payloads must be JSON-safe and bounded. */
+    sanitize(event) {
+        if (!event || typeof event !== 'object')
+            return event;
+        let safe = event;
+        // A finished agent turn may carry the whole history — the panel never
+        // uses it and it would dwarf every other frame.
+        if (safe.type === 'done' && 'messages' in safe) {
+            const { messages: _messages, ...rest } = safe;
+            safe = rest;
+        }
+        if (safe.error instanceof Error) {
+            safe = { ...safe, error: safe.error.message };
+        }
+        const json = JSON.stringify(safe);
+        if (json.length <= MAX_EVENT_JSON_CHARS)
+            return safe;
+        return {
+            type: safe.type || 'event',
+            truncated: true,
+            originalChars: json.length,
+            message: `${safe.type || 'event'} payload was truncated to keep SSE memory bounded.`,
+            preview: `${json.slice(0, MAX_EVENT_JSON_CHARS - 1)}…`,
+        };
+    }
+    cleanup() {
+        const cutoff = Date.now() - MAX_RUN_AGE_MS;
+        for (const [id, run] of this.runs) {
+            if (run.createdAt < cutoff)
+                this.runs.delete(id);
+        }
+    }
+}

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/AiAssistantHandler.d.ts

@@ -1,17 +1,28 @@
-import { Adminizer } from '../Adminizer';
-import { AbstractAiModelService } from './AbstractAiModelService';
-import { AiAssistantMessage, AiAssistantModelInfo } from '../../interfaces/types';
-import { User } from '../../models/User';
+import { Adminizer } from '../Adminizer.js';
+import { AbstractAiModelService } from './AbstractAiModelService.js';
+import { AiAssistantMessage, AiAssistantModelInfo } from '../../interfaces/types.js';
+import { User } from '../../models/User.js';
 export declare class AiAssistantHandler {
     private readonly adminizer;
     private readonly models;
+    private readonly owners;
     private readonly history;
     constructor(adminizer: Adminizer);
-    registerModel(service: AbstractAiModelService): void;
+    /**
+     * @param owner App name when the model belongs to an app. Models without an
+     * owner belong to the host application and are never removed automatically.
+     */
+    registerModel(service: AbstractAiModelService, owner?: string): void;
+    /**
+     * @param owner When passed, the model is kept if it is owned by someone
+     * else, so a disabled app never removes another owner's model.
+     */
+    unregisterModel(id: string, owner?: string): void;
     getModel(id: string): AbstractAiModelService | undefined;
     getModels(): AiAssistantModelInfo[];
     getHistory(userId: number, modelId: string): AiAssistantMessage[];
     resetHistory(userId: number, modelId: string): void;
+    replaceHistory(userId: number, modelId: string, history: AiAssistantMessage[]): void;
     sendMessage(user: User, modelId: string, prompt: string): Promise<{
         history: AiAssistantMessage[];
     }>;