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

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,61 @@
+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>;
+    } | Promise<{
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    } | undefined> | 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): Promise<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,90 @@
+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. */
+    async getAvailable(user) {
+        const available = [];
+        for (const skill of this.skills.values()) {
+            if (await this.isPermitted(skill, user))
+                available.push(await this.describe(skill, user));
+        }
+        return available;
+    }
+    async execute(id, input, user) {
+        const skill = this.skills.get(id.trim().toLowerCase());
+        if (!skill || !await 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),
+        };
+    }
+    async isPermitted(skill, user) {
+        return !skill.accessRightsToken || this.adminizer.accessRightsHelper.hasPermission(skill.accessRightsToken, user);
+    }
+    async describe(skill, user) {
+        const refinement = await 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

@@ -22,6 +22,7 @@ export declare class AiAssistantHandler {
     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[];
     }>;

package/lib/ai-assistant/AiAssistantHandler.js

@@ -16,6 +16,7 @@ export class AiAssistantHandler {
         if (this.models.has(service.id)) {
             Adminizer.log.warn(`AI assistant model with id "${service.id}" is already registered. Overwriting.`);
         }
+        service.attachAdminizer(this.adminizer);
         this.models.set(service.id, service);
         if (owner) {
             this.owners.set(service.id, owner);
@@ -55,6 +56,9 @@ export class AiAssistantHandler {
     resetHistory(userId, modelId) {
         this.history.delete(this.getSessionKey(userId, modelId));
     }
+    replaceHistory(userId, modelId, history) {
+        this.history.set(this.getSessionKey(userId, modelId), history);
+    }
     async sendMessage(user, modelId, prompt) {
         const service = this.getModel(modelId);
         if (!service) {

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

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

package/lib/ai-assistant/AiAssistantUiMethodHandler.js

@@ -0,0 +1,144 @@
+import { listAccessibleMenuItems } from '../../helpers/navigationAccessHelper.js';
+export class AiAssistantUiMethodHandler {
+    adminizer;
+    methods = new Map();
+    owners = new Map();
+    constructor(adminizer) {
+        this.adminizer = adminizer;
+        this.register({
+            id: 'navigate',
+            title: 'Open admin section',
+            description: 'Open an Adminizer page in the current browser tab using the Inertia router.'
+                + ' Pass `href` for a concrete link, or `template` plus `params` for a parametrized page'
+                + ' such as a single record. Both come from search-admin-links.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    href: { type: 'string', description: 'Adminizer-relative URL of a concrete page to open.' },
+                    template: { type: 'string', description: 'Id of a link template returned by search-admin-links.' },
+                    params: {
+                        type: 'object',
+                        description: 'Values for the template placeholders, e.g. {"id": "3860d321-…"}.',
+                        additionalProperties: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+            action: 'navigate',
+        });
+        this.register({
+            id: 'search-admin-links',
+            title: 'Search admin sections and links',
+            description: 'Search the current user\'s accessible Adminizer navigation sections, links and'
+                + ' link templates (record pages, catalog items and other parametrized pages).',
+            inputSchema: {
+                type: 'object',
+                properties: { query: { type: 'string', description: 'Words to search in section, link and template titles.' } },
+                required: ['query'], additionalProperties: false,
+            },
+            action: 'search-admin-links',
+        });
+    }
+    register(method, owner) {
+        const id = method.id.trim().toLowerCase();
+        if (!/^[a-z][a-z0-9_-]*$/.test(id))
+            throw new Error(`Invalid AI assistant UI method id: ${method.id}`);
+        if (!method.title.trim() || !method.description.trim())
+            throw new Error(`AI assistant UI method "${id}" requires title and description`);
+        this.methods.set(id, { ...method, id });
+        if (owner)
+            this.owners.set(id, owner);
+        else
+            this.owners.delete(id);
+    }
+    unregister(id, owner) {
+        const normalized = id.trim().toLowerCase();
+        if (owner && this.owners.get(normalized) !== owner)
+            return;
+        this.methods.delete(normalized);
+        this.owners.delete(normalized);
+    }
+    async getAvailable(user) {
+        const available = [];
+        for (const method of this.methods.values()) {
+            if (method.accessRightsToken
+                && !await this.adminizer.accessRightsHelper.hasPermission(method.accessRightsToken, user)) {
+                continue;
+            }
+            available.push({ ...method, inputSchema: { ...method.inputSchema } });
+        }
+        return available;
+    }
+    /**
+     * Search exactly the navigation a user can open.  This intentionally uses
+     * MenuHelper rather than client-side markup, therefore a tool result is
+     * permission-safe and works when the assistant panel is not visible.
+     *
+     * Parametrized pages are returned as templates, so a record page is
+     * reachable even though its URL only exists once the id is known.
+     */
+    async searchAdminLinks(user, query = '') {
+        const needle = this.slug(query);
+        const result = [];
+        const matches = (...values) => !needle || this.slug(values.filter(Boolean).join(' ')).includes(needle);
+        const add = (item, section) => {
+            if (!item?.link || !item?.title)
+                return;
+            const link = {
+                id: String(item.id || item.title), title: String(item.title), link: String(item.link),
+                section: item.section || section,
+            };
+            // A link with placeholders is surfaced as a template instead.
+            if (!/:[A-Za-z0-9_]+/.test(link.link) && matches(link.title, link.id, link.section))
+                result.push(link);
+            for (const child of item.actions ?? item.subItems ?? [])
+                add(child, link.section);
+        };
+        // Exactly the menu the sidebar renders for this user, sub-items included.
+        for (const item of await listAccessibleMenuItems(this.adminizer, user))
+            add(item, item.section);
+        for (const template of await this.adminizer.adminLinkHandler.listTemplates(user)) {
+            if (!matches(template.title, template.id, template.section, template.description, template.template))
+                continue;
+            result.push({
+                id: template.id,
+                title: template.title,
+                template: template.template,
+                params: template.params,
+                description: template.description,
+                section: template.section,
+                // A template without placeholders is already a usable link.
+                link: template.params.length ? undefined : template.template,
+            });
+        }
+        return result;
+    }
+    /**
+     * Validates what an agent asked to open and returns the concrete admin URL.
+     * Templates are resolved against this user's own permissions, so the LLM
+     * can only reach pages that user could reach by clicking.
+     */
+    async resolveNavigation(user, target) {
+        const template = target.template?.trim();
+        if (template) {
+            return this.adminizer.adminLinkHandler.resolveTemplate(user, template, target.params ?? {});
+        }
+        const href = target.href?.trim();
+        if (!href)
+            throw new Error('Navigation requires either href or template');
+        const prefix = (this.adminizer.config.routePrefix || '').replace(/\/+$/, '');
+        if (href !== prefix && !href.startsWith(`${prefix}/`)) {
+            throw new Error('Only Adminizer-relative links may be opened.');
+        }
+        if (/:[A-Za-z0-9_]+/.test(href)) {
+            throw new Error('This link is a template: pass it as `template` together with `params`.');
+        }
+        if (this.adminizer.adminLinkHandler.isDestructivePath(href)) {
+            throw new Error('This page changes data and cannot be opened by the assistant.');
+        }
+        return href;
+    }
+    slug(value) {
+        return String(value ?? '').trim().toLowerCase().replace(/[\s_-]+/g, '-');
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { Adminizer } from '../Adminizer.js';
+import type { AiAssistantAgentSkill } from './AiAssistantAgentSkillHandler.js';
+/**
+ * Skills every agent gets for free: who it is talking to, and read/edit access
+ * scoped to exactly the data that user may reach in the admin panel. Because
+ * every call re-checks the user's permissions, an agent built on them can be
+ * offered to non-administrator accounts as well.
+ */
+export declare function buildBuiltinAgentSkills(adminizer: Adminizer): AiAssistantAgentSkill[];