@adminforth/agent 1.0.0

package/custom/skills/fetch_data/SKILL.md

@@ -0,0 +1,15 @@
+name: fetch_data
+description: Fetch one or more records. Use to find records entities. To use this skill you first need to call get_resource tool to know resource column names. This tool returns only atomic record(s) not capable with any aggregations.
+---
+
+# Involved tools
+
+You can use tool `get_resource_data` it returns one or more records and is capable of using filters
+
+# Instructions
+
+To find specific data record you should use filters. ILIKE filters are preferred when we are unsure the input is clear.You can combine filters with OR if you want to search multiple fields.If user queries one record you should try to fetch up to 5 records and if more then one returned return output them all to user and ask to select one. When you communicate about record with user, show its several most important fields.
+
+For long texts show only several first words and add "..." at the end (only if user did not request this field specifically).
+
+Also when you communicate with user about record, add related link to this record. For example /{BASE_URL}/resource/{resourceId}/show/{primary key}. Use _label from `get_resource_data` as anchor text for link (use markdown link).

package/custom/skills/mutate_data/SKILL.md

@@ -0,0 +1,108 @@
+name: mutate_data
+description:  Create/update/delete some record of resource or call actions on one or multiple records
+---
+
+# General rules
+
+- if there is a dedicated action for some routine (result of `get_resource` tool call, field actions), prefer this to manual updating of records, for example, if you want to approve some comment, prefer calling `approve` action instead of updating `approved` field of comment record (because in action there might be some additional logic like sending notification to user, updating some counters and so on)
+
+## Confirmation
+
+Before performing any state mutation including action calls edit/delete please fetch record which is going to be edited/deleted and show user record in format field → value (show several most important fields which can help user to understand what exactly record he is going to edit or delete). 
+
+For field values with long texts show only several first words and add "..." at the end.
+Also please add related link to record with will be changed. For example /{BASE_URL}/resource/{resourceId}/show/{primary key}. Use _label from `get_resource_data` as anchor text for link (use markdown link).
+And in the same message ask user for final confirmation.
+
+When creating new record, show user all data which you gona create and in same message ask for confirmation.
+
+Accept any positive confirmation from user like "yes", "sure", "+", anything non-negative call to action, can be considered as confirmation. 
+
+# Calling actions
+
+To call action on some record you can use `start_custom_action` tool,  or `start_custom_bulk_action` if you need to perform action on several records at once. 
+
+Before calling any of this action you should understand whether this action is allowed. User result of `get_resource` tool call and check `action.allowed` - if this attribute is true or is not exists, assume action is allowed. If this attribute is false, action is not allowed, you should warn user that this action is not allowed for him.
+
+### Example
+
+If you want to block some user you can confirm that this action by saying:
+
+```I am going to block user:
+* Username: john_doe
+* Email: john_doe@example.com
+* IP Country: USA
+* Currently blocked: No // show this field only if it exists in user record
+
+View [John Doe](/resource/users/show/123)
+Are you sure?
+```
+
+## Updating
+
+You can use tool `update_record` tool it updates fields of record. To update `allowedActions.edit` should be set to true and 
+`updated` column `showIn.edit` should be true at the same time. If one of this condition is not met, explain to user that is 
+not allowed to edit
+
+In addition to instructions above show user the table of edits (old value/new value)
+
+### Examples
+
+For example if you gonna modify user record, in confirmation please share full user info (not only username but also email, ip country - anything which help adminto check that that is correct user). Message could look like this:
+
+```
+I am going to update user:
+* Username: john_doe
+* Email: john_doe@example.com
+* IP Country: USA
+I am going to change email from john_doe@example.com to new_email@example.com
+
+View [John Doe](/admin/resource/users/show/123)
+
+Are you sure?
+```
+
+
+## Deleting
+
+To delete some record you can use `delete_record` tool. To delete record `allowedActions.delete` should be set to true.
+
+### Example 
+
+If you gonna delete user record, in confirmation please share full user info (not only username but also email, ip country - anything which help adminto check that that is correct user). Message could look like this:
+
+```I am going to delete user:
+* Username: john_doe
+* Email: john_doe@example.com
+* Signed up: 2024 Jan 1
+* IP Country: USA
+
+View [John Doe](/admin/resource/users/show/123)
+
+Are you sure?
+```
+
+## Creating
+
+To create new record you can use tool `create_record`. To create record `allowedActions.create` should be set to true.
+
+When calling `create_record` tool pass only columns which have `showIn.create` set to true and `backendOnly` is not set to true.
+
+For decimal fields please use string values with dot as decimal separator.
+
+After creation of new record also show user a link to this record. If several records record were created, show links to all of them in list.
+
+Omit any pictures or file paths, you are not capable of doing it. If they are not required all is good, if they are required, explain to user that you are not able to create record because of this reason.
+
+### Example
+
+
+```
+I am going to create user:
+* Username: john_doe
+* Email: john_doe@example.com
+
+View [John Doe](/admin/resource/users/show/421) # 421 is id of new created record
+
+Are you sure?
+```

package/custom/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".", // This should point to your project root
+    "paths": {
+      "@/*": [
+        "../node_modules/adminforth/dist/spa/src/*"
+      ],
+      "*": [
+        "../node_modules/adminforth/dist/spa/node_modules/*"
+      ],
+      "@@/*": [
+        "."
+      ]
+    }
+  }
+}

package/custom/types.ts

@@ -0,0 +1,34 @@
+export interface IPartData {
+  toolCallId: string;
+  toolName: string;
+  phase: 'start' | 'end';
+  input?: any;
+  output?: any;
+  durationMs?: number;
+}
+export interface IPart {
+  type: string;
+  text?: string;
+  state?: 'started' | 'thinking' | 'processing' | 'streaming' | 'done';
+  data?: IPartData;
+}
+
+export interface IMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  metadata?: any,
+  parts: IPart[];
+}
+
+export interface IAgentSession {
+  sessionId: string;
+  title: string;
+  timestamp: string;
+  messages: IMessage[];
+}
+
+export interface ISessionsListItem {
+  sessionId: string;
+  title: string;
+  timestamp: string;
+}

package/custom/useAgentStore.ts

@@ -0,0 +1,349 @@
+import { defineStore } from 'pinia';
+import { IAgentSession, ISessionsListItem, IMessage } from './types';
+import { ref, nextTick, computed, watch, onMounted, shallowRef } from 'vue';
+import { callAdminForthApi } from '@/utils';
+import { useAdminforth } from '@/adminforth';
+import { Chat } from "@ai-sdk/vue";
+import { DefaultChatTransport } from 'ai';
+import { useCoreStore } from '@/stores/core';
+
+export const useAgentStore = defineStore('agent', () => {
+  const activeSessionId = ref<string | null>(null);
+  const currentSession = ref<IAgentSession | null>(null);
+  const sessionList = ref<ISessionsListItem[]>([]);
+  const sessions = ref<Record<string, IAgentSession>>({});
+  const adminforth = useAdminforth();
+  const isChatOpen = ref(false);
+  const isSessionHistoryOpen = ref(false);
+  const textInput = ref<HTMLInputElement | null>(null);
+  const userMessageInput = ref();
+  const trimmedUserMessage = computed(() => userMessageInput.value ? userMessageInput.value.trim() : '');
+  const lastMessage = ref('');
+  const isTeleportedToBody = ref(false);
+  const setIsTeleportedToBody = (isTeleported: boolean) => {
+    isTeleportedToBody.value = isTeleported;
+  }
+  const coreStore = useCoreStore();
+  const appRoot = ref<HTMLElement | null>(null);
+  const header = ref<HTMLElement | null>(null);
+  const chatWidth = ref(600);
+  function setLocalStorageItem(key: string, value: string) {
+    window.localStorage.setItem(`${coreStore.config.brandName || 'adminforth'}-${key}`, value);
+  }
+  function getLocalStorageItem(key: string) {
+    return window.localStorage.getItem(`${coreStore.config.brandName || 'adminforth'}-${key}`);
+  }
+  watch(isTeleportedToBody, (newVal: boolean) => {
+    setLocalStorageItem('isTeleportedToBody', newVal ? 'true' : 'false');
+  })
+  watch(isChatOpen, (newVal: boolean) => {
+    setLocalStorageItem('isChatOpen', newVal ? 'true' : 'false');
+  })
+  watch(chatWidth, (newVal: number) => {
+    setLocalStorageItem('chatWidth', newVal.toString());
+  })
+  onMounted(() => {
+    chatWidth.value = parseInt(getLocalStorageItem('chatWidth') || '600', 10);
+    isTeleportedToBody.value = getLocalStorageItem('isTeleportedToBody') === 'true';
+    if (isTeleportedToBody.value) {
+      isChatOpen.value = getLocalStorageItem('isChatOpen') === 'true';
+    }
+    if (coreStore.isMobile) {
+      chatWidth.value = window.innerWidth;
+    }
+    appRoot.value = document.getElementById('app');
+    header.value = document.getElementById('af-header-nav');
+    if (appRoot.value && header.value) {
+      nextTick(() => {
+        appRoot.value.style.transition = 'padding-right 200ms ease-in-out';
+        header.value.style.transition = 'padding-right 200ms ease-in-out';
+      });
+    }  
+  })
+  function setChatWidth(width: number) {
+    if (appRoot.value && header.value) {
+      appRoot.value.style.transition = '';
+      header.value.style.transition = '';
+    }
+    chatWidth.value = width;
+
+  }
+  watch([isTeleportedToBody, isChatOpen, chatWidth], ([newIsTeleportedToBody, newIsChatOpen, newChatWidth]: [boolean, boolean, number]) => {
+    if (appRoot.value && header.value) {
+      if (newIsTeleportedToBody && newIsChatOpen) {
+        appRoot.value.style.paddingRight = `${chatWidth.value}px`;
+        header.value.style.paddingRight = `${chatWidth.value}px`;
+      } else {
+        appRoot.value.style.paddingRight = '';
+        header.value.style.paddingRight = '';
+      }
+    }
+  })
+  const chats = new Map<string, Chat>();
+  const currentChat = shallowRef<Chat>(null);
+  function setCurrentChat(sessionId: string) {
+    if (chats.has(sessionId)) {
+      currentChat.value = chats.get(sessionId) || null;
+    } else {
+      const newChat = new Chat({
+        transport: new DefaultChatTransport({
+          api: `${import.meta.env.VITE_ADMINFORTH_PUBLIC_PATH || ''}/adminapi/v1/agent/response`,
+          credentials: 'include',
+          prepareSendMessagesRequest({ messages }: any) {
+            const message = lastMessage.value;
+            const body = {
+              message,
+              sessionId,
+              timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            };
+
+            return {
+              headers: {
+                Accept: 'text/event-stream',
+                'x-vercel-ai-ui-message-stream': 'v1',
+              },
+              body
+            };
+          }
+        }),
+        onError(error: unknown) {
+          console.error("Chat error:", error);
+        },
+      });
+      chats.set(sessionId, newChat);
+      currentChat.value = newChat;
+    }
+
+  }
+  const isResponseInProgress = computed( () => {
+    return currentChat.value?.status === 'streaming';
+  });
+  const blockCloseOfChat = ref(false);
+
+  async function sendMessage() {
+    const message = trimmedUserMessage.value;
+    if (!message || isResponseInProgress.value) {
+      return;
+    }
+    if (!currentSession.value || currentSession.value.sessionId === 'pre-session') {
+      await createNewSession(message);
+    }
+    lastMessage.value = message;
+    currentChat.value?.sendMessage({
+      text: message,
+    });
+    userMessageInput.value = '';
+  }
+
+  function closeChat() {
+    if (blockCloseOfChat.value) {
+      return;
+    }
+    isChatOpen.value = false;
+    isSessionHistoryOpen.value = false;
+  }
+
+  function openChat() {
+    isChatOpen.value = true;
+    nextTick(() => {
+      textInput.value?.focus();
+    });
+  }
+
+  function setIsChatOpen(isOpen: boolean) {
+    isOpen ? openChat() : closeChat();
+  }
+
+  function setSessionHistoryOpen(isOpen: boolean) {
+    isSessionHistoryOpen.value = isOpen;
+  }
+  function regisrerTextInput(el: HTMLInputElement | null) {
+    textInput.value = el;
+  }
+
+
+  //create a pre-session, until user will type something, so we can save session
+  async function createPreSession() {
+    saveCurrentSessionInCache();
+    if (sessionList.value.some((s: ISessionsListItem) => s.sessionId === 'pre-session')) {
+      return;
+    }
+    sessionList.value.unshift({
+      sessionId: 'pre-session',
+      title: 'New Session',
+      timestamp: new Date().toISOString(),
+    })
+    activeSessionId.value = 'pre-session';
+    currentSession.value = {
+      sessionId: 'pre-session',
+      title: 'New Session',
+      timestamp: new Date().toISOString(),
+      messages: [],
+    };
+    sessions.value['pre-session'] = currentSession.value;
+    setCurrentChat('pre-session');
+  }
+
+  async function deletePreSession() {
+    sessionList.value = sessionList.value.filter((s: ISessionsListItem) => s.sessionId !== 'pre-session');
+    if (activeSessionId.value === 'pre-session') {
+      activeSessionId.value = null;
+      currentSession.value = null;
+    }
+  }
+
+  async function createNewSession(triggerMessage?: string) {
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/create-session',
+        body: { 
+          triggerMessage
+        },
+      });
+      if (res.error) {
+        console.error('Error creating new session:', res.error);
+        return;
+      }
+      deletePreSession();
+      sessions.value[res.sessionId] = res;
+      sessionList.value.unshift({
+        sessionId: res.sessionId,
+        title: res.title,
+        timestamp: new Date().toISOString(),
+      });
+      setActiveSession(res.sessionId);
+    } catch (error) {
+      console.error('Error creating new session', error);
+    }
+  }
+
+  async function deleteSession(sessionId: string) {
+    if (sessionId === 'pre-session') {
+      deletePreSession();
+      return;
+    }
+    blockCloseOfChat.value = true;
+    const isConfirmed = await adminforth.confirm({message: 'Are you sure, that you want to delete this session?', yes: 'Yes', no: 'No'})
+    blockCloseOfChat.value = false;
+    if (!isConfirmed) {
+      return;
+    }
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/delete-session',
+        body: { sessionId },
+      });
+      if (res.error) {
+        console.error('Error deleting session:', res.error);
+        return;
+      }
+      delete sessions.value[sessionId];
+      sessionList.value = sessionList.value.filter((s: ISessionsListItem) => s.sessionId !== sessionId);
+      if (activeSessionId.value === sessionId) {
+        activeSessionId.value = null;
+        currentSession.value = null;
+      }
+    } catch (error) {
+      console.error('Error deleting session', error);
+    }
+    if(sessionId === activeSessionId.value) {
+      activeSessionId.value = sessionList.value.length > 0 ? sessionList.value[0].sessionId : null;
+      if (activeSessionId.value) {
+        currentSession.value = sessions.value[activeSessionId.value] || null;
+      } else {
+        currentSession.value = null;
+      }
+    }
+  }
+
+  async function fetchSession(sessionId: string) {
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/get-session-info',
+        body: { sessionId },
+      });
+      if (res.error) {
+        console.error('Error fetching session:', res.error);
+        return;
+      }
+      sessions.value[sessionId] = res.session;
+      setCurrentChat(sessionId);
+    } catch (error) {
+      console.error('Error fetching session', error);
+    }
+  }
+
+  function saveCurrentSessionInCache() {
+    if (currentSession.value) {
+      currentSession.value.messages = currentChat.value?.messages.map((m: any) => ({
+        role: m.role,
+        text: m.parts.map((p: any) => p.text).join(' '),
+      })) || [];
+      sessions.value[currentSession.value.sessionId] = currentSession.value;
+    }
+  }
+
+  async function setActiveSession(sessionId: string) {
+    activeSessionId.value = sessionId;
+    saveCurrentSessionInCache();
+    if (!sessions.value[sessionId]) {
+      await fetchSession(sessionId);    
+    }
+    currentSession.value = sessions.value[sessionId];
+    setCurrentChat(sessionId);
+    currentChat.value.messages = currentSession.value?.messages.map((m: any) => ({
+      role: m.role,
+      parts:[{
+        type: 'text',
+        text: m.text,
+        state: 'done',
+      }]
+    }));
+  }
+
+  async function fetchSessionsList() {
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/get-sessions',
+      });
+      if (res.error) {
+        console.error('Error fetching sessions list:', res.error);
+        return;
+      }
+      sessionList.value = res.sessions;
+    } catch (error) {
+      console.error('Error fetching sessions list', error);
+    }
+  }
+
+  return {
+    //_________-Sessions management-_____________
+    activeSessionId,
+    currentSession,
+    sessions,
+    sessionList,
+    setActiveSession,
+    fetchSessionsList,
+    deleteSession,
+    createPreSession,
+    //____________________________________________
+    regisrerTextInput,
+    isChatOpen,
+    setIsChatOpen,
+    isSessionHistoryOpen,
+    setSessionHistoryOpen,
+    sendMessage,
+    userMessageInput,
+    chatMessages: computed(() => currentChat.value?.messages || []),
+    trimmedUserMessage,
+    isResponseInProgress,
+    isTeleportedToBody,
+    setIsTeleportedToBody,
+    chatWidth,
+    setChatWidth,
+  }
+})

package/dist/agent/middleware/apiBasedTools.js

@@ -0,0 +1,91 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ToolMessage } from "@langchain/core/messages";
+import { createMiddleware } from "langchain";
+import { logger } from "adminforth";
+import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "../tools/index.js";
+import { createApiTool } from "../tools/apiTool.js";
+function getEnabledApiToolNames(messages) {
+    const enabledToolNames = new Set();
+    for (const message of messages) {
+        if (!ToolMessage.isInstance(message) || message.name !== "fetch_tool_schema") {
+            continue;
+        }
+        const content = typeof message.content === "string"
+            ? message.content
+            : Array.isArray(message.content)
+                ? message.content
+                    .map((block) => typeof block === "string"
+                    ? block
+                    : "text" in block
+                        ? block.text
+                        : "")
+                    .join("")
+                : "";
+        try {
+            const parsed = JSON.parse(content);
+            if (parsed.status === 200 && parsed.name) {
+                enabledToolNames.add(parsed.name);
+            }
+        }
+        catch (_a) { }
+    }
+    return enabledToolNames;
+}
+export function createApiBasedToolsMiddleware(apiBasedTools) {
+    const alwaysAvailableApiToolNames = new Set(ALWAYS_AVAILABLE_API_TOOL_NAMES);
+    const dynamicTools = Object.fromEntries(Object.entries(apiBasedTools).map(([toolName, apiBasedTool]) => [
+        toolName,
+        createApiTool(toolName, apiBasedTool),
+    ]));
+    return createMiddleware({
+        name: "ApiBasedToolsMiddleware",
+        wrapModelCall(request, handler) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const enabledApiToolNames = getEnabledApiToolNames(request.state.messages);
+                const tools = [...enabledApiToolNames]
+                    .filter((toolName) => !alwaysAvailableApiToolNames.has(toolName))
+                    .map((toolName) => dynamicTools[toolName]);
+                return handler(Object.assign(Object.assign({}, request), { tools: [...request.tools, ...tools] }));
+            });
+        },
+        wrapToolCall(request, handler) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c;
+                const startedAt = Date.now();
+                const toolInput = JSON.stringify((_a = request.toolCall.args) !== null && _a !== void 0 ? _a : {});
+                logger.info(`Invoking tool "${request.toolCall.name}" with input: ${toolInput}`);
+                try {
+                    if (request.tool) {
+                        return yield handler(request);
+                    }
+                    const enabledApiToolNames = getEnabledApiToolNames(request.state.messages);
+                    if (enabledApiToolNames.has(request.toolCall.name)) {
+                        return yield handler(Object.assign(Object.assign({}, request), { tool: dynamicTools[request.toolCall.name] }));
+                    }
+                    return new ToolMessage({
+                        content: `Tool "${request.toolCall.name}" is not loaded. Call fetch_tool_schema first.`,
+                        tool_call_id: (_b = request.toolCall.id) !== null && _b !== void 0 ? _b : "",
+                        name: request.toolCall.name,
+                        status: "error",
+                    });
+                }
+                catch (error) {
+                    const errorDetails = error instanceof Error ? (_c = error.stack) !== null && _c !== void 0 ? _c : error.message : String(error);
+                    logger.error(`Tool "${request.toolCall.name}" failed after ${Date.now() - startedAt}ms with input: ${toolInput}\n${errorDetails}`);
+                    throw error;
+                }
+                finally {
+                    logger.info(`Tool "${request.toolCall.name}" finished in ${Date.now() - startedAt}ms`);
+                }
+            });
+        },
+    });
+}