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

package/controllers/ai/AiAgentController.js

@@ -0,0 +1,435 @@
+import multer from 'multer';
+import { Adminizer } from '../../lib/Adminizer.js';
+import { AiAgentRunManager } from '../../lib/ai-assistant/AiAgentRunManager.js';
+const MAX_FILES = 5;
+const MAX_FILE_SIZE = 8 * 1024 * 1024;
+/**
+ * Inline cap per text attachment: roughly 64k tokens, half of a typical 128k
+ * context window, so a single file cannot immediately trigger compaction.
+ */
+const MAX_INLINE_TEXT_CHARS = 256 * 1024;
+const TEXT_EXTENSIONS = new Set([
+    'txt', 'md', 'markdown', 'csv', 'tsv', 'json', 'yaml', 'yml', 'xml', 'html', 'css',
+    'js', 'ts', 'jsx', 'tsx', 'sql', 'log', 'ini', 'conf', 'env', 'sh', 'graphql',
+]);
+const TEXT_MIME_TYPES = new Set([
+    'application/json', 'application/xml', 'application/x-yaml', 'application/sql', 'image/svg+xml',
+]);
+const runs = new AiAgentRunManager();
+// multer only engages on multipart/form-data; JSON bodies pass through untouched.
+const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: MAX_FILE_SIZE, files: MAX_FILES, fieldSize: 1024 * 1024 },
+}).array('files', MAX_FILES);
+function isTextFile(file) {
+    const mime = file.mimetype || '';
+    if (mime.startsWith('text/'))
+        return true;
+    if (TEXT_MIME_TYPES.has(mime))
+        return true;
+    const ext = (file.originalname || '').split('.').pop()?.toLowerCase() || '';
+    return TEXT_EXTENSIONS.has(ext);
+}
+/** Turns prompt + uploaded files into an ai-sdk ModelMessage[] for the agent. */
+function buildInput(prompt, files, vision, savedFiles = []) {
+    if (!files?.length)
+        return prompt;
+    const parts = [];
+    if (prompt)
+        parts.push({ type: 'text', text: prompt });
+    for (let index = 0; index < files.length; index += 1) {
+        const file = files[index];
+        const saved = savedFiles[index];
+        const name = file.originalname || 'file';
+        const savedNote = saved?.id
+            ? ` saved_file_id=${JSON.stringify(saved.id)} saved_file_name=${JSON.stringify(saved.name || name)}`
+            : '';
+        if (isTextFile(file)) {
+            let text = file.buffer.toString('utf8');
+            let note = '';
+            if (text.length > MAX_INLINE_TEXT_CHARS) {
+                text = text.slice(0, MAX_INLINE_TEXT_CHARS);
+                note = `\n[attachment truncated at ${MAX_INLINE_TEXT_CHARS} characters]`;
+            }
+            parts.push({
+                type: 'text',
+                text: `<attachment name=${JSON.stringify(name)}${savedNote}>\n${text}${note}\n</attachment>`,
+            });
+        }
+        else if ((file.mimetype || '').startsWith('image/')) {
+            if (vision) {
+                parts.push({ type: 'image', image: `data:${file.mimetype};base64,${file.buffer.toString('base64')}` });
+            }
+            else {
+                parts.push({
+                    type: 'text',
+                    text: `[Image attached: ${name}${saved?.id ? `, saved_file_id=${saved.id}` : ''} — the current model cannot see images]`,
+                });
+            }
+        }
+        else {
+            parts.push({
+                type: 'text',
+                text: `[Unsupported attachment saved but not inlined: ${name}${saved?.id ? `, saved_file_id=${saved.id}` : ''} (${file.mimetype || 'unknown type'})]`,
+            });
+        }
+    }
+    return [{ role: 'user', content: parts }];
+}
+/**
+ * Streaming agent endpoints, consumed by the assistant panel bundle
+ * (src/assets/js/ai-assistant).
+ *
+ * Every route is scoped to one registered model service; permissions are
+ * enforced by the router (`ai-assistant-<modelId>`). Services that implement
+ * only `generateReply` are supported too — their answer is streamed as a
+ * single text frame, so one UI serves both kinds.
+ */
+export class AiAgentController {
+    /** GET /api/ai-assistant/agent/:modelId/status */
+    static async getStatus(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service)
+            return;
+        const locale = AiAgentController.resolveLocale(req);
+        const schema = {
+            ...service.getUiSchema(locale),
+            uiMethods: req.adminizer.aiAssistantUiMethodHandler.getAvailable(req.user),
+        };
+        if (typeof service.getConnectionStatus !== 'function') {
+            res.json({ state: 'ready', locale, schema });
+            return;
+        }
+        try {
+            const status = await service.getConnectionStatus();
+            res.json({ ...status, locale, schema });
+        }
+        catch (error) {
+            Adminizer.log.error('AI agent status check failed', error);
+            res.status(500).json({ error: error?.message || 'Status check failed' });
+        }
+    }
+    /** GET /api/ai-assistant/agent/:modelId/limits */
+    static async getLimits(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service || !await AiAgentController.ensureReady(service, res))
+            return;
+        if (typeof service.getLimits !== 'function') {
+            res.json({ provider: service.id, supported: false });
+            return;
+        }
+        const forceRefresh = req.query.refresh === '1' || req.query.refresh === 'true';
+        try {
+            const limits = await service.getLimits(forceRefresh);
+            res.json(limits ?? { provider: service.id, supported: false });
+        }
+        catch (error) {
+            res.status(500).json({ error: error?.message || 'Failed to read limits' });
+        }
+    }
+    /** GET /api/ai-assistant/agent/:modelId/meta */
+    static async getMeta(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service || !await AiAgentController.ensureReady(service, res))
+            return;
+        try {
+            res.json(await AiAgentController.buildMeta(service, req));
+        }
+        catch (error) {
+            Adminizer.log.error('AI agent meta failed', error);
+            res.status(500).json({ error: error?.message || 'Failed to load agent info' });
+        }
+    }
+    /** POST /api/ai-assistant/agent/:modelId/model */
+    static async setModel(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service || !await AiAgentController.ensureReady(service, res))
+            return;
+        if (typeof service.setCurrentModel !== 'function') {
+            res.status(501).json({ error: 'This assistant does not support switching models' });
+            return;
+        }
+        const model = typeof req.body?.model === 'string' ? req.body.model.trim() : '';
+        if (!model) {
+            res.status(400).json({ error: 'Model is required.' });
+            return;
+        }
+        try {
+            await service.setCurrentModel(req.user, model);
+            res.json(await AiAgentController.buildMeta(service, req));
+        }
+        catch (error) {
+            res.status(500).json({ error: error?.message || 'Failed to switch the model' });
+        }
+    }
+    /** GET /api/ai-assistant/agent/:modelId/history */
+    static async getHistory(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service)
+            return;
+        const messages = await AiAgentController.syncActiveConversation(service, req);
+        res.json({ messages });
+    }
+    /** GET /api/ai-assistant/agent/:modelId/conversations */
+    static async listConversations(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service)
+            return;
+        await AiAgentController.syncActiveConversation(service, req);
+        const active = service.conversationHistory.getActive(req.user);
+        res.json({ activeId: active.id, conversations: service.conversationHistory.list(req.user).map(AiAgentController.serializeConversation) });
+    }
+    /** POST /api/ai-assistant/agent/:modelId/conversations */
+    static async createConversation(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service)
+            return;
+        await AiAgentController.syncActiveConversation(service, req);
+        const title = typeof req.body?.title === 'string' ? req.body.title.trim().slice(0, 120) : undefined;
+        const conversation = service.conversationHistory.create(req.user, title || undefined);
+        await AiAgentController.restoreConversation(service, req, conversation.messages);
+        res.status(201).json({ conversation: AiAgentController.serializeConversation(conversation) });
+    }
+    /** POST /api/ai-assistant/agent/:modelId/conversations/:conversationId/select */
+    static async selectConversation(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service)
+            return;
+        await AiAgentController.syncActiveConversation(service, req);
+        const conversation = service.conversationHistory.select(req.user, req.params.conversationId);
+        if (!conversation) {
+            res.sendStatus(404);
+            return;
+        }
+        await AiAgentController.restoreConversation(service, req, conversation.messages);
+        res.json({ conversation: AiAgentController.serializeConversation(conversation) });
+    }
+    /** DELETE /api/ai-assistant/agent/:modelId/conversations/:conversationId */
+    static async deleteConversation(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service)
+            return;
+        const conversationId = req.params.conversationId;
+        const active = service.conversationHistory.getActive(req.user);
+        if (active.id === conversationId) {
+            res.status(400).json({ error: 'Create or select another conversation before deleting this one' });
+            return;
+        }
+        res.json({ deleted: service.conversationHistory.remove(req.user, conversationId) });
+    }
+    /**
+     * POST /api/ai-assistant/agent/:modelId/runs
+     *
+     * Starts a turn and answers 202 with the stream URL. The run itself is
+     * kicked off after the response so the browser can open the EventSource
+     * before the first frame is published.
+     */
+    static async startRun(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service || !await AiAgentController.ensureReady(service, res))
+            return;
+        upload(req, res, async (uploadError) => {
+            if (uploadError) {
+                const message = uploadError.code === 'LIMIT_FILE_SIZE'
+                    ? `File is too large (max ${Math.round(MAX_FILE_SIZE / 1024 / 1024)}MB)`
+                    : uploadError.message || 'Upload failed';
+                res.status(413).json({ error: message });
+                return;
+            }
+            const prompt = typeof req.body?.message === 'string' ? req.body.message.trim() : '';
+            const files = req.files || [];
+            if (!prompt && !files.length) {
+                res.status(400).json({ error: 'Message is required' });
+                return;
+            }
+            try {
+                const savedFiles = typeof service.saveUploadedFiles === 'function'
+                    ? await service.saveUploadedFiles(req.user, files)
+                    : [];
+                const vision = Boolean(service.getSessionMeta?.(req.user)?.vision);
+                const input = buildInput(prompt || 'See the attached files.', files, vision, savedFiles);
+                const run = runs.create(req.user.id, service.id);
+                const prefix = req.adminizer.config.routePrefix;
+                res.status(202).json({
+                    runId: run.id,
+                    stream: `${prefix}/api/ai-assistant/agent/${encodeURIComponent(service.id)}/runs/${run.id}/stream`,
+                });
+                setImmediate(() => {
+                    void (async () => {
+                        try {
+                            await AiAgentController.execute(service, req, input, prompt, (event) => runs.publish(run, event));
+                            runs.finish(run, { type: 'done' });
+                        }
+                        catch (error) {
+                            Adminizer.log.error('AI agent run failed', error);
+                            runs.finish(run, { type: 'error', error: error?.message || 'Agent run failed' });
+                        }
+                    })();
+                });
+            }
+            catch (error) {
+                Adminizer.log.error('AI agent run could not be started', error);
+                res.status(500).json({ error: error?.message || 'Failed to start the run' });
+            }
+        });
+    }
+    /** GET /api/ai-assistant/agent/:modelId/runs/:runId/stream */
+    static async streamRun(req, res) {
+        const service = AiAgentController.resolveService(req, res);
+        if (!service)
+            return;
+        const run = runs.get(req.params.runId, req.user.id);
+        if (!run || run.modelId !== service.id) {
+            res.sendStatus(404);
+            return;
+        }
+        runs.subscribe(run, req, res);
+    }
+    /**
+     * Streaming agents publish their own frames; a legacy `generateReply` model
+     * is wrapped into the same protocol so the panel needs no special case.
+     */
+    static async execute(service, req, input, prompt, publish) {
+        const commandResult = await service.executeChatCommand(prompt, input, req.user, publish);
+        if (commandResult) {
+            if (commandResult.text) {
+                publish({ type: 'text.delta', text: commandResult.text });
+                publish({ type: 'text.done' });
+            }
+            publish({ type: 'turn.done' });
+            if (commandResult.persist !== false && commandResult.text) {
+                await AiAgentController.appendCommandToSession(service, req, prompt, commandResult.text);
+            }
+            service.conversationHistory.saveActive(req.user, AiAgentController.getSessionMessages(service, req));
+            return;
+        }
+        if (service.isStreamingAgent()) {
+            await service.streamReply(input, req.user, publish);
+            service.conversationHistory.saveActive(req.user, AiAgentController.getSessionMessages(service, req));
+            return;
+        }
+        const { history } = await req.adminizer.aiAssistantHandler.sendMessage(req.user, service.id, prompt);
+        service.conversationHistory.saveActive(req.user, history.map((message) => ({
+            role: message.role,
+            content: [{ type: 'text', text: message.content }],
+        })));
+        const reply = history[history.length - 1]?.content ?? '';
+        publish({ type: 'text.delta', text: reply });
+        publish({ type: 'text.done' });
+        publish({ type: 'turn.done' });
+    }
+    /** Session meta plus the model catalogue and the upload caps of this transport. */
+    static async buildMeta(service, req) {
+        const availableModels = typeof service.getModelChoices === 'function'
+            // Warming the catalogue first means a cold-start meta call reports a
+            // real discovered model instead of a configured placeholder.
+            ? await service.getModelChoices()
+            : [];
+        const meta = service.getSessionMeta?.(req.user) ?? {
+            model: service.id,
+            contextWindow: 0,
+            vision: false,
+            turns: req.adminizer.aiAssistantHandler.getHistory(req.user.id, service.id).length,
+            contextTokens: 0,
+            totalUsage: {},
+        };
+        return { ...meta, availableModels, maxFiles: MAX_FILES, maxFileSize: MAX_FILE_SIZE };
+    }
+    static getSessionMessages(service, req) {
+        if (typeof service.getSessionHistory === 'function')
+            return service.getSessionHistory(req.user);
+        return req.adminizer.aiAssistantHandler.getHistory(req.user.id, service.id).map((message) => ({
+            role: message.role,
+            content: [{ type: 'text', text: message.content }],
+        }));
+    }
+    /**
+     * The persisted dialog is restored into a fresh agent session before it is
+     * saved again. This keeps initial demo dialogs and database-backed history
+     * intact when an agent has not created its in-memory session yet.
+     */
+    static async syncActiveConversation(service, req) {
+        const messages = AiAgentController.getSessionMessages(service, req);
+        const active = service.conversationHistory.getActive(req.user);
+        if (messages.length === 0 && active.messages.length > 0) {
+            await AiAgentController.restoreConversation(service, req, active.messages);
+            return active.messages;
+        }
+        service.conversationHistory.saveActive(req.user, messages);
+        return messages;
+    }
+    static async restoreConversation(service, req, messages) {
+        if (typeof service.restoreSessionHistory === 'function') {
+            await service.restoreSessionHistory(req.user, messages);
+            return;
+        }
+        if (typeof service.getSessionHistory === 'function') {
+            throw new Error('This agent does not support restoring conversations yet.');
+        }
+        req.adminizer.aiAssistantHandler.replaceHistory(req.user.id, service.id, messages.map((message) => {
+            const content = Array.isArray(message.content) ? message.content : [];
+            const text = content.find((part) => part?.type === 'text')?.text ?? '';
+            return { id: `${Date.now()}-${Math.random()}`, role: message.role, content: String(text), timestamp: new Date(), modelId: service.id };
+        }));
+    }
+    /** Persists command turns just like ordinary chat turns for both agent kinds. */
+    static async appendCommandToSession(service, req, prompt, response) {
+        const messages = [
+            ...AiAgentController.getSessionMessages(service, req),
+            { role: 'user', content: [{ type: 'text', text: prompt }] },
+            { role: 'assistant', content: [{ type: 'text', text: response }] },
+        ];
+        await AiAgentController.restoreConversation(service, req, messages);
+    }
+    static serializeConversation(conversation) {
+        return conversation;
+    }
+    /**
+     * Resolves the registered model service for this request, answering the
+     * response itself when the assistant is off, unknown or unusable.
+     */
+    static resolveService(req, res) {
+        if (!req.adminizer.config.aiAssistant?.enabled) {
+            res.status(503).json({ error: 'AI assistant is disabled' });
+            return null;
+        }
+        const handler = req.adminizer.aiAssistantHandler;
+        if (!handler) {
+            res.status(500).json({ error: 'AI assistant is not available' });
+            return null;
+        }
+        const modelId = req.params?.modelId;
+        const service = modelId ? handler.getModel(modelId) : undefined;
+        if (!service) {
+            res.status(404).json({ error: `AI assistant model not found: ${modelId}` });
+            return null;
+        }
+        return service;
+    }
+    /** Endpoints that talk to the LLM also require a provisioned connection. */
+    static async ensureReady(service, res) {
+        if (typeof service.getConnectionStatus !== 'function')
+            return true;
+        const status = await service.getConnectionStatus();
+        if (status?.state === 'ready')
+            return true;
+        res.status(503).json({
+            error: 'The assistant is not connected to an LLM endpoint yet.',
+            status,
+        });
+        return false;
+    }
+    /** Admin UI language, resolved the way Inertia shares it with the pages. */
+    static resolveLocale(req) {
+        const translation = req.adminizer.config.translation;
+        const defaultLocale = typeof translation !== 'boolean' ? translation?.defaultLocale ?? 'en' : 'en';
+        const available = typeof translation !== 'boolean' ? translation?.locales ?? [] : [];
+        const requested = String(req.user?.locale || defaultLocale);
+        const normalized = requested.replace('_', '-').split('-')[0];
+        if (available.includes(requested))
+            return requested;
+        if (available.includes(normalized))
+            return normalized;
+        return defaultLocale;
+    }
+}

package/controllers/ai/AiAssistantController.d.ts

@@ -1,7 +1,3 @@
 export declare class AiAssistantController {
     static getModels(req: ReqType, res: ResType): Promise<ResType>;
-    static getHistory(req: ReqType, res: ResType): Promise<ResType>;
-    static sendMessage(req: ReqType, res: ResType): Promise<ResType>;
-    static resetHistory(req: ReqType, res: ResType): Promise<ResType>;
-    private static serializeMessage;
 }

package/controllers/ai/AiAssistantController.js

@@ -9,84 +9,10 @@ export class AiAssistantController {
             Adminizer.log.warn('AI assistant handler is not initialized');
             return res.json([]);
         }
-        const models = handler
-            .getModels()
-            .filter((model) => req.adminizer.accessRightsHelper.hasPermission(`ai-assistant-${model.id}`, req.user));
+        const models = (await Promise.all(handler.getModels().map(async (model) => ({
+            model,
+            allowed: await req.adminizer.accessRightsHelper.hasPermission(`ai-assistant-${model.id}`, req.user),
+        })))).filter(({ allowed }) => allowed).map(({ model }) => model);
         return res.json(models);
     }
-    static async getHistory(req, res) {
-        if (!req.adminizer.config.aiAssistant?.enabled) {
-            return res.json({ history: [] });
-        }
-        const { modelId } = req.params;
-        if (!modelId) {
-            return res.status(400).json({ error: 'Model id is required' });
-        }
-        if (!req.adminizer.accessRightsHelper.hasPermission(`ai-assistant-${modelId}`, req.user)) {
-            return res.status(403).json({ error: 'Forbidden' });
-        }
-        const handler = req.adminizer.aiAssistantHandler;
-        if (!handler) {
-            return res.status(500).json({ error: 'AI assistant is not available' });
-        }
-        const history = handler.getHistory(req.user.id, modelId).map(AiAssistantController.serializeMessage);
-        return res.json({ history });
-    }
-    static async sendMessage(req, res) {
-        if (!req.adminizer.config.aiAssistant?.enabled) {
-            return res.status(503).json({ error: 'AI assistant is disabled' });
-        }
-        const { modelId, message } = req.body;
-        if (!modelId || typeof modelId !== 'string') {
-            return res.status(400).json({ error: 'Model id is required' });
-        }
-        if (!message || typeof message !== 'string' || message.trim().length === 0) {
-            return res.status(400).json({ error: 'Message is required' });
-        }
-        if (!req.adminizer.accessRightsHelper.hasPermission(`ai-assistant-${modelId}`, req.user)) {
-            return res.status(403).json({ error: 'Forbidden' });
-        }
-        const handler = req.adminizer.aiAssistantHandler;
-        if (!handler) {
-            return res.status(500).json({ error: 'AI assistant is not available' });
-        }
-        try {
-            const response = await handler.sendMessage(req.user, modelId, message.trim());
-            return res.json({
-                modelId,
-                history: response.history.map(AiAssistantController.serializeMessage),
-            });
-        }
-        catch (error) {
-            Adminizer.log.error('AI assistant error', error);
-            return res.status(500).json({ error: 'Failed to process request' });
-        }
-    }
-    static async resetHistory(req, res) {
-        if (!req.adminizer.config.aiAssistant?.enabled) {
-            return res.status(503).json({ error: 'AI assistant is disabled' });
-        }
-        const { modelId } = req.params;
-        if (!modelId) {
-            return res.status(400).json({ error: 'Model id is required' });
-        }
-        if (!req.adminizer.accessRightsHelper.hasPermission(`ai-assistant-${modelId}`, req.user)) {
-            return res.status(403).json({ error: 'Forbidden' });
-        }
-        const handler = req.adminizer.aiAssistantHandler;
-        if (!handler) {
-            return res.status(500).json({ error: 'AI assistant is not available' });
-        }
-        handler.resetHistory(req.user.id, modelId);
-        return res.json({ history: [] });
-    }
-    static serializeMessage(message) {
-        return {
-            id: message.id,
-            role: message.role,
-            content: message.content,
-            timestamp: message.timestamp instanceof Date ? message.timestamp.toISOString() : message.timestamp,
-            modelId: message.modelId,
-        };
-    }
 }

package/controllers/catalog/FrontendCatalogAdapter.d.ts

@@ -1,4 +1,4 @@
-import { AbstractCatalog, Item } from "../../lib/catalog/AbstractCatalog";
+import { AbstractCatalog, Item } from "../../lib/catalog/AbstractCatalog.js";
 interface NodeModel<TDataType> {
     text: string;
     droppable: boolean;

package/controllers/catalog/FrontentCatalogAdapter.d.ts

@@ -1,4 +1,4 @@
-import { AbstractCatalog, Item } from "../../lib/catalog/AbstractCatalog";
+import { AbstractCatalog, Item } from "../../lib/catalog/AbstractCatalog.js";
 interface NodeModel<TDataType> {
     text: string;
     droppable: boolean;

package/controllers/docs/index.d.ts

@@ -0,0 +1,22 @@
+export declare function docsList(req: ReqType, res: ResType): Promise<ResType>;
+export declare function docsKeywords(req: ReqType, res: ResType): Promise<ResType>;
+export declare function docsSearch(req: ReqType, res: ResType): Promise<ResType>;
+export declare function docsContext(req: ReqType, res: ResType): Promise<ResType>;
+export declare function docsDoc(req: ReqType, res: ResType): Promise<ResType>;
+/**
+ * Resolves references written inside a document to document ids. How a
+ * reference is spelled is the implementation's business; the viewer only
+ * learns which of them point at a document this user may open — the rest stay
+ * unresolved and are rendered as plain text.
+ */
+export declare function docsResolve(req: ReqType, res: ResType): Promise<ResType>;
+/**
+ * The viewer page. The document itself is fetched by the page through the API,
+ * so a deep link only has to name the document it opens with.
+ */
+export declare function docsPage(req: ReqType): Promise<import("express").Response<any, Record<string, any>>>;
+/**
+ * Structure of a model resource as this user is allowed to see it — the same
+ * fields DataAccessor would hand to the list page, nothing more.
+ */
+export declare function docsSchema(req: ReqType, res: ResType): Promise<ResType>;