@adminforth/agent 1.14.1 → 1.16.0

package/agent/systemPrompt.ts

@@ -35,10 +35,21 @@ export const DEFAULT_AGENT_SYSTEM_PROMPT = [
   "If the confirmed plan has multiple steps, you may execute the whole confirmed plan without asking again between those steps.",
   "If the plan changes, expands, or you want to do anything beyond the confirmed plan, ask for confirmation again.",
   "Do not reuse an old confirmation for a new mutation plan.",
-
-  
 ].join(" ");
 
+export function appendCustomSystemPrompt(
+  systemPrompt: string,
+  customSystemPrompt?: string,
+) {
+  const normalizedCustomSystemPrompt = customSystemPrompt?.trim();
+
+  if (!normalizedCustomSystemPrompt) {
+    return systemPrompt;
+  }
+
+  return `${systemPrompt}\n\n${normalizedCustomSystemPrompt}`;
+}
+
 function formatResources(resources: AdminForthResource[]) {
   return resources
     .map((resource) => `- resourceId: ${resource.resourceId}\n  label: ${resource.label}`)

package/build.log

@@ -31,5 +31,5 @@ custom/skills/fetch_data/SKILL.md
 custom/skills/mutate_data/
 custom/skills/mutate_data/SKILL.md
 
-sent 180,483 bytes  received 436 bytes  361,838.00 bytes/sec
-total size is 178,690  speedup is 0.99
+sent 184,204 bytes  received 436 bytes  369,280.00 bytes/sec
+total size is 182,411  speedup is 0.99

package/custom/ChatSurface.vue

@@ -111,7 +111,7 @@
                 'min-h-12 w-full resize-none overflow-hidden border text-lightInputText dark:text-darkInputText rounded-md bg-transparent text-sm bg-gray-50 dark:bg-gray-700 dark:border-gray-600 focus:outline-none',
                 agentStore.availableModes.length > 1 ? 'p-4 pr-12 pb-12' : 'p-4 pr-12',
               ]"
-              placeholder="Type a message..."
+              :placeholder="agentStore.userMessagePlaceholder"
               @keydown.enter.exact.prevent="sendMessage"
             />
             <div

package/custom/ConversationArea.vue

@@ -74,7 +74,7 @@
 <script setup lang="ts">
 import Message from './Message.vue';
 import type { IMessage, IPart } from './types';
-import { useTemplateRef, ref, defineAsyncComponent, onMounted, watch, computed } from 'vue';
+import { useTemplateRef, ref, defineAsyncComponent, onMounted, onUnmounted, watch, computed } from 'vue';
 import { IconArrowDownOutline } from '@iconify-prerendered/vue-flowbite';
 import SessionsHistory from './SessionsHistory.vue';
 import { useAgentStore } from './composables/useAgentStore';
@@ -98,6 +98,11 @@ function recalculateScroll() {
 
 onMounted(async () => {
   await import('@incremark/theme/styles.css')
+  await agentStore.fetchPlaceholderMessages()
+});
+
+onUnmounted(() => {
+  agentStore.stopPlaceholderAnimation();
 });
 
 watch(scrollContainer, () => {

package/custom/composables/useAgentStore.ts

@@ -12,6 +12,11 @@ type AgentMode = {
   name: string;
 };
 
+const DEFAULT_TEXTAREA_PLACEHOLDER = 'Type a message...';
+const PLACEHOLDER_TYPING_DELAY_MS = 60;
+const PLACEHOLDER_DELETING_DELAY_MS = 35;
+const PLACEHOLDER_HOLD_DELAY_MS = 3000;
+
 export const useAgentStore = defineStore('agent', () => {
   const DEFAULT_CHAT_WIDTH = 600;
   const MAX_WIDTH = 800;
@@ -25,8 +30,10 @@ export const useAgentStore = defineStore('agent', () => {
   const adminforth = useAdminforth();
   const isChatOpen = ref(false);
   const isSessionHistoryOpen = ref(false);
-  const textInput = ref<HTMLInputElement | null>(null);
+  const textInput = ref<HTMLTextAreaElement | null>(null);
   const userMessageInput = ref();
+  const userMessagePlaceholder = ref(DEFAULT_TEXTAREA_PLACEHOLDER);
+  const placeholderMessages = ref<string[]>([]);
   const trimmedUserMessage = computed(() => userMessageInput.value ? userMessageInput.value.trim() : '');
   const lastMessage = ref('');
   const isTeleportedToBody = ref(false);
@@ -40,6 +47,9 @@ export const useAgentStore = defineStore('agent', () => {
   const chatWidth = ref(DEFAULT_CHAT_WIDTH);
   const availableModes = ref<AgentMode[]>([]);
   const activeModeName = ref<string | null>(null);
+  const hasTypedMessageInPageSession = ref(false);
+  let placeholderAnimationTimer: ReturnType<typeof setTimeout> | null = null;
+
   function setLocalStorageItem(key: string, value: string) {
     window.localStorage.setItem(`${coreStore.config.brandName || 'adminforth'}-${key}`, value);
   }
@@ -60,6 +70,16 @@ export const useAgentStore = defineStore('agent', () => {
       setLocalStorageItem('lastSessionId', newVal);
     }
   })
+  watch(userMessageInput, (newVal: unknown) => {
+    if (hasTypedMessageInPageSession.value) {
+      return;
+    }
+
+    if (typeof newVal === 'string' && newVal.trim() !== '') {
+      hasTypedMessageInPageSession.value = true;
+      stopPlaceholderAnimation();
+    }
+  })
   onMounted(() => {
     const chatWidthBeforeFullScreen = parseInt(getLocalStorageItem('chatWidthBeforeFullScreen') || '0', 10);
     if (chatWidthBeforeFullScreen) {
@@ -130,14 +150,14 @@ export const useAgentStore = defineStore('agent', () => {
   function setAvailableModes(modes: AgentMode[], defaultModeName?: string | null) {
     availableModes.value = modes;
     activeModeName.value =
-      modes.find((mode) => mode.name === activeModeName.value)?.name
+      modes.find((mode: AgentMode) => mode.name === activeModeName.value)?.name
       ?? defaultModeName
       ?? modes[0]?.name
       ?? null;
   }
 
   function setActiveMode(modeName: string) {
-    if (!availableModes.value.some((mode) => mode.name === modeName)) {
+    if (!availableModes.value.some((mode: AgentMode) => mode.name === modeName)) {
       return;
     }
 
@@ -179,6 +199,73 @@ export const useAgentStore = defineStore('agent', () => {
     }
 
   }
+
+  function clearPlaceholderAnimationTimer() {
+    if (placeholderAnimationTimer !== null) {
+      clearTimeout(placeholderAnimationTimer);
+      placeholderAnimationTimer = null;
+    }
+  }
+
+  function resetPlaceholder() {
+    clearPlaceholderAnimationTimer();
+    userMessagePlaceholder.value = DEFAULT_TEXTAREA_PLACEHOLDER;
+  }
+
+  function stopPlaceholderAnimation() {
+    resetPlaceholder();
+  }
+
+  function startPlaceholderAnimation(messages: string[]) {
+    clearPlaceholderAnimationTimer();
+
+    if (!messages.length) {
+      userMessagePlaceholder.value = DEFAULT_TEXTAREA_PLACEHOLDER;
+      return;
+    }
+
+    let messageIndex = 0;
+    let visibleLength = 0;
+    let isDeleting = false;
+
+    const animate = () => {
+      const currentMessage = messages[messageIndex];
+
+      if (!currentMessage) {
+        resetPlaceholder();
+        return;
+      }
+
+      if (!isDeleting) {
+        visibleLength += 1;
+        userMessagePlaceholder.value = currentMessage.slice(0, visibleLength);
+
+        if (visibleLength >= currentMessage.length) {
+          isDeleting = true;
+          placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_HOLD_DELAY_MS);
+          return;
+        }
+
+        placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_TYPING_DELAY_MS);
+        return;
+      }
+
+      visibleLength -= 1;
+      userMessagePlaceholder.value = currentMessage.slice(0, Math.max(visibleLength, 0));
+
+      if (visibleLength <= 0) {
+        isDeleting = false;
+        messageIndex = (messageIndex + 1) % messages.length;
+        placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_TYPING_DELAY_MS);
+        return;
+      }
+
+      placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_DELETING_DELAY_MS);
+    };
+
+    animate();
+  }
+
   const isResponseInProgress = computed( () => {
     return currentChat.value?.status === 'streaming';
   });
@@ -234,10 +321,46 @@ export const useAgentStore = defineStore('agent', () => {
   function setSessionHistoryOpen(isOpen: boolean) {
     isSessionHistoryOpen.value = isOpen;
   }
-  function regisrerTextInput(el: HTMLInputElement | null) {
+  function regisrerTextInput(el: HTMLTextAreaElement | null) {
     textInput.value = el;
   }
 
+  async function fetchPlaceholderMessages() {
+    if (hasTypedMessageInPageSession.value) {
+      stopPlaceholderAnimation();
+      return;
+    }
+
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/get-placeholder-messages',
+      });
+
+      if (res.error) {
+        console.error('Error fetching placeholder messages:', res.error);
+        placeholderMessages.value = [];
+        resetPlaceholder();
+        return;
+      }
+
+      placeholderMessages.value = Array.isArray(res.messages)
+        ? res.messages.filter((message: unknown): message is string => typeof message === 'string' && message.length > 0)
+        : [];
+
+      if (!placeholderMessages.value.length) {
+        resetPlaceholder();
+        return;
+      }
+
+      startPlaceholderAnimation(placeholderMessages.value);
+    } catch (error) {
+      console.error('Error fetching placeholder messages', error);
+      placeholderMessages.value = [];
+      resetPlaceholder();
+    }
+  }
+
 
   //create a pre-session, until user will type something, so we can save session
   async function createPreSession() {
@@ -409,12 +532,15 @@ export const useAgentStore = defineStore('agent', () => {
     createPreSession,
     //____________________________________________
     regisrerTextInput,
+    fetchPlaceholderMessages,
+    stopPlaceholderAnimation,
     isChatOpen,
     setIsChatOpen,
     isSessionHistoryOpen,
     setSessionHistoryOpen,
     sendMessage,
     userMessageInput,
+    userMessagePlaceholder,
     chatMessages: computed(() => currentChat.value?.messages || []),
     trimmedUserMessage,
     isResponseInProgress,

package/dist/agent/systemPrompt.js

@@ -35,6 +35,13 @@ export const DEFAULT_AGENT_SYSTEM_PROMPT = [
     "If the plan changes, expands, or you want to do anything beyond the confirmed plan, ask for confirmation again.",
     "Do not reuse an old confirmation for a new mutation plan.",
 ].join(" ");
+export function appendCustomSystemPrompt(systemPrompt, customSystemPrompt) {
+    const normalizedCustomSystemPrompt = customSystemPrompt === null || customSystemPrompt === void 0 ? void 0 : customSystemPrompt.trim();
+    if (!normalizedCustomSystemPrompt) {
+        return systemPrompt;
+    }
+    return `${systemPrompt}\n\n${normalizedCustomSystemPrompt}`;
+}
 function formatResources(resources) {
     return resources
         .map((resource) => `- resourceId: ${resource.resourceId}\n  label: ${resource.label}`)

package/dist/custom/ChatSurface.vue

@@ -111,7 +111,7 @@
                 'min-h-12 w-full resize-none overflow-hidden border text-lightInputText dark:text-darkInputText rounded-md bg-transparent text-sm bg-gray-50 dark:bg-gray-700 dark:border-gray-600 focus:outline-none',
                 agentStore.availableModes.length > 1 ? 'p-4 pr-12 pb-12' : 'p-4 pr-12',
               ]"
-              placeholder="Type a message..."
+              :placeholder="agentStore.userMessagePlaceholder"
               @keydown.enter.exact.prevent="sendMessage"
             />
             <div

package/dist/custom/ConversationArea.vue

@@ -74,7 +74,7 @@
 <script setup lang="ts">
 import Message from './Message.vue';
 import type { IMessage, IPart } from './types';
-import { useTemplateRef, ref, defineAsyncComponent, onMounted, watch, computed } from 'vue';
+import { useTemplateRef, ref, defineAsyncComponent, onMounted, onUnmounted, watch, computed } from 'vue';
 import { IconArrowDownOutline } from '@iconify-prerendered/vue-flowbite';
 import SessionsHistory from './SessionsHistory.vue';
 import { useAgentStore } from './composables/useAgentStore';
@@ -98,6 +98,11 @@ function recalculateScroll() {
 
 onMounted(async () => {
   await import('@incremark/theme/styles.css')
+  await agentStore.fetchPlaceholderMessages()
+});
+
+onUnmounted(() => {
+  agentStore.stopPlaceholderAnimation();
 });
 
 watch(scrollContainer, () => {

package/dist/custom/composables/useAgentStore.ts

@@ -12,6 +12,11 @@ type AgentMode = {
   name: string;
 };
 
+const DEFAULT_TEXTAREA_PLACEHOLDER = 'Type a message...';
+const PLACEHOLDER_TYPING_DELAY_MS = 60;
+const PLACEHOLDER_DELETING_DELAY_MS = 35;
+const PLACEHOLDER_HOLD_DELAY_MS = 3000;
+
 export const useAgentStore = defineStore('agent', () => {
   const DEFAULT_CHAT_WIDTH = 600;
   const MAX_WIDTH = 800;
@@ -25,8 +30,10 @@ export const useAgentStore = defineStore('agent', () => {
   const adminforth = useAdminforth();
   const isChatOpen = ref(false);
   const isSessionHistoryOpen = ref(false);
-  const textInput = ref<HTMLInputElement | null>(null);
+  const textInput = ref<HTMLTextAreaElement | null>(null);
   const userMessageInput = ref();
+  const userMessagePlaceholder = ref(DEFAULT_TEXTAREA_PLACEHOLDER);
+  const placeholderMessages = ref<string[]>([]);
   const trimmedUserMessage = computed(() => userMessageInput.value ? userMessageInput.value.trim() : '');
   const lastMessage = ref('');
   const isTeleportedToBody = ref(false);
@@ -40,6 +47,9 @@ export const useAgentStore = defineStore('agent', () => {
   const chatWidth = ref(DEFAULT_CHAT_WIDTH);
   const availableModes = ref<AgentMode[]>([]);
   const activeModeName = ref<string | null>(null);
+  const hasTypedMessageInPageSession = ref(false);
+  let placeholderAnimationTimer: ReturnType<typeof setTimeout> | null = null;
+
   function setLocalStorageItem(key: string, value: string) {
     window.localStorage.setItem(`${coreStore.config.brandName || 'adminforth'}-${key}`, value);
   }
@@ -60,6 +70,16 @@ export const useAgentStore = defineStore('agent', () => {
       setLocalStorageItem('lastSessionId', newVal);
     }
   })
+  watch(userMessageInput, (newVal: unknown) => {
+    if (hasTypedMessageInPageSession.value) {
+      return;
+    }
+
+    if (typeof newVal === 'string' && newVal.trim() !== '') {
+      hasTypedMessageInPageSession.value = true;
+      stopPlaceholderAnimation();
+    }
+  })
   onMounted(() => {
     const chatWidthBeforeFullScreen = parseInt(getLocalStorageItem('chatWidthBeforeFullScreen') || '0', 10);
     if (chatWidthBeforeFullScreen) {
@@ -130,14 +150,14 @@ export const useAgentStore = defineStore('agent', () => {
   function setAvailableModes(modes: AgentMode[], defaultModeName?: string | null) {
     availableModes.value = modes;
     activeModeName.value =
-      modes.find((mode) => mode.name === activeModeName.value)?.name
+      modes.find((mode: AgentMode) => mode.name === activeModeName.value)?.name
       ?? defaultModeName
       ?? modes[0]?.name
       ?? null;
   }
 
   function setActiveMode(modeName: string) {
-    if (!availableModes.value.some((mode) => mode.name === modeName)) {
+    if (!availableModes.value.some((mode: AgentMode) => mode.name === modeName)) {
       return;
     }
 
@@ -179,6 +199,73 @@ export const useAgentStore = defineStore('agent', () => {
     }
 
   }
+
+  function clearPlaceholderAnimationTimer() {
+    if (placeholderAnimationTimer !== null) {
+      clearTimeout(placeholderAnimationTimer);
+      placeholderAnimationTimer = null;
+    }
+  }
+
+  function resetPlaceholder() {
+    clearPlaceholderAnimationTimer();
+    userMessagePlaceholder.value = DEFAULT_TEXTAREA_PLACEHOLDER;
+  }
+
+  function stopPlaceholderAnimation() {
+    resetPlaceholder();
+  }
+
+  function startPlaceholderAnimation(messages: string[]) {
+    clearPlaceholderAnimationTimer();
+
+    if (!messages.length) {
+      userMessagePlaceholder.value = DEFAULT_TEXTAREA_PLACEHOLDER;
+      return;
+    }
+
+    let messageIndex = 0;
+    let visibleLength = 0;
+    let isDeleting = false;
+
+    const animate = () => {
+      const currentMessage = messages[messageIndex];
+
+      if (!currentMessage) {
+        resetPlaceholder();
+        return;
+      }
+
+      if (!isDeleting) {
+        visibleLength += 1;
+        userMessagePlaceholder.value = currentMessage.slice(0, visibleLength);
+
+        if (visibleLength >= currentMessage.length) {
+          isDeleting = true;
+          placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_HOLD_DELAY_MS);
+          return;
+        }
+
+        placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_TYPING_DELAY_MS);
+        return;
+      }
+
+      visibleLength -= 1;
+      userMessagePlaceholder.value = currentMessage.slice(0, Math.max(visibleLength, 0));
+
+      if (visibleLength <= 0) {
+        isDeleting = false;
+        messageIndex = (messageIndex + 1) % messages.length;
+        placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_TYPING_DELAY_MS);
+        return;
+      }
+
+      placeholderAnimationTimer = setTimeout(animate, PLACEHOLDER_DELETING_DELAY_MS);
+    };
+
+    animate();
+  }
+
   const isResponseInProgress = computed( () => {
     return currentChat.value?.status === 'streaming';
   });
@@ -234,10 +321,46 @@ export const useAgentStore = defineStore('agent', () => {
   function setSessionHistoryOpen(isOpen: boolean) {
     isSessionHistoryOpen.value = isOpen;
   }
-  function regisrerTextInput(el: HTMLInputElement | null) {
+  function regisrerTextInput(el: HTMLTextAreaElement | null) {
     textInput.value = el;
   }
 
+  async function fetchPlaceholderMessages() {
+    if (hasTypedMessageInPageSession.value) {
+      stopPlaceholderAnimation();
+      return;
+    }
+
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/get-placeholder-messages',
+      });
+
+      if (res.error) {
+        console.error('Error fetching placeholder messages:', res.error);
+        placeholderMessages.value = [];
+        resetPlaceholder();
+        return;
+      }
+
+      placeholderMessages.value = Array.isArray(res.messages)
+        ? res.messages.filter((message: unknown): message is string => typeof message === 'string' && message.length > 0)
+        : [];
+
+      if (!placeholderMessages.value.length) {
+        resetPlaceholder();
+        return;
+      }
+
+      startPlaceholderAnimation(placeholderMessages.value);
+    } catch (error) {
+      console.error('Error fetching placeholder messages', error);
+      placeholderMessages.value = [];
+      resetPlaceholder();
+    }
+  }
+
 
   //create a pre-session, until user will type something, so we can save session
   async function createPreSession() {
@@ -409,12 +532,15 @@ export const useAgentStore = defineStore('agent', () => {
     createPreSession,
     //____________________________________________
     regisrerTextInput,
+    fetchPlaceholderMessages,
+    stopPlaceholderAnimation,
     isChatOpen,
     setIsChatOpen,
     isSessionHistoryOpen,
     setSessionHistoryOpen,
     sendMessage,
     userMessageInput,
+    userMessagePlaceholder,
     chatMessages: computed(() => currentChat.value?.messages || []),
     trimmedUserMessage,
     isResponseInProgress,

package/dist/index.js

@@ -20,7 +20,7 @@ import { HumanMessage, SystemMessage } from "langchain";
 import { createAgentChatModel, callAgent } from "./agent/simpleAgent.js";
 import { createSequenceDebugCollector } from "./agent/middleware/sequenceDebug.js";
 import { prepareApiBasedTools as buildApiBasedTools, } from './apiBasedTools.js';
-import { buildAgentSystemPrompt, DEFAULT_AGENT_SYSTEM_PROMPT, } from "./agent/systemPrompt.js";
+import { appendCustomSystemPrompt, buildAgentSystemPrompt, DEFAULT_AGENT_SYSTEM_PROMPT, } from "./agent/systemPrompt.js";
 import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "./agent/tools/index.js";
 function isAggregateErrorLike(error) {
     return typeof error === "object" && error !== null && Array.isArray(error.errors);
@@ -91,8 +91,8 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     constructor(options) {
         super(options, import.meta.url);
         this.apiBasedTools = {};
-        this.agentSystemPromptPromise = Promise.resolve(DEFAULT_AGENT_SYSTEM_PROMPT);
         this.options = options;
+        this.agentSystemPromptPromise = Promise.resolve(appendCustomSystemPrompt(DEFAULT_AGENT_SYSTEM_PROMPT, this.options.systemPrompt));
         this.shouldHaveSingleInstancePerWholeApp = () => false;
     }
     modifyResourceConfig(adminforth, resourceConfig) {
@@ -127,12 +127,38 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             assertRequiredApiTool(this.apiBasedTools, toolName);
         }
         assertRequiredApiTool(this.apiBasedTools, "update_record");
-        this.agentSystemPromptPromise = buildAgentSystemPrompt(adminforth);
+        this.agentSystemPromptPromise = buildAgentSystemPrompt(adminforth)
+            .then((systemPrompt) => appendCustomSystemPrompt(systemPrompt, this.options.systemPrompt));
     }
     instanceUniqueRepresentation(pluginOptions) {
         return `single`;
     }
     setupEndpoints(server) {
+        server.endpoint({
+            method: 'POST',
+            path: `/agent/get-placeholder-messages`,
+            handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, query, headers, cookies, adminUser, response, requestUrl }) {
+                if (!this.options.placeholderMessages) {
+                    return {
+                        messages: [],
+                    };
+                }
+                const messages = yield this.options.placeholderMessages({
+                    adminUser,
+                    httpExtra: {
+                        body,
+                        query,
+                        headers,
+                        cookies,
+                        requestUrl,
+                        response,
+                    },
+                });
+                return {
+                    messages,
+                };
+            })
+        });
         server.endpoint({
             method: 'POST',
             path: `/agent/response`,

package/index.ts

@@ -16,6 +16,7 @@ import {
 } from './apiBasedTools.js';
 import type { ApiBasedTool } from './apiBasedTools.js';
 import {
+  appendCustomSystemPrompt,
   buildAgentSystemPrompt,
   DEFAULT_AGENT_SYSTEM_PROMPT,
 } from "./agent/systemPrompt.js";
@@ -67,7 +68,7 @@ function assertRequiredApiTool(
 export default class AdminForthAgentPlugin extends AdminForthPlugin {
   options: PluginOptions;
   apiBasedTools: Record<string, ApiBasedTool> = {};
-  agentSystemPromptPromise = Promise.resolve(DEFAULT_AGENT_SYSTEM_PROMPT);
+  agentSystemPromptPromise: Promise<string>;
 
   private async createNewTurn(sessionId: string, prompt: string, response?: string) {
     const turnId = randomUUID();
@@ -109,6 +110,9 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
   constructor(options: PluginOptions) {
     super(options, import.meta.url);
     this.options = options;
+    this.agentSystemPromptPromise = Promise.resolve(
+      appendCustomSystemPrompt(DEFAULT_AGENT_SYSTEM_PROMPT, this.options.systemPrompt),
+    );
     this.shouldHaveSingleInstancePerWholeApp = () => false;
   }
 
@@ -139,7 +143,8 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       assertRequiredApiTool(this.apiBasedTools, toolName);
     }
     assertRequiredApiTool(this.apiBasedTools, "update_record");
-    this.agentSystemPromptPromise = buildAgentSystemPrompt(adminforth);
+    this.agentSystemPromptPromise = buildAgentSystemPrompt(adminforth)
+      .then((systemPrompt) => appendCustomSystemPrompt(systemPrompt, this.options.systemPrompt));
   }
 
   instanceUniqueRepresentation(pluginOptions: any) : string {
@@ -147,6 +152,33 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
   }
 
   setupEndpoints(server: IHttpServer) {
+    server.endpoint({
+      method: 'POST',
+      path: `/agent/get-placeholder-messages`,
+      handler: async ({ body, query, headers, cookies, adminUser, response, requestUrl }) => {
+        if (!this.options.placeholderMessages) {
+          return {
+            messages: [],
+          };
+        }
+
+        const messages = await this.options.placeholderMessages({
+          adminUser,
+          httpExtra: {
+            body,
+            query,
+            headers,
+            cookies,
+            requestUrl,
+            response,
+          },
+        });
+
+        return {
+          messages,
+        };
+      }
+    });
     server.endpoint({
       method: 'POST',
       path: `/agent/response`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/agent",
-  "version": "1.14.1",
+  "version": "1.16.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/types.ts

@@ -1,4 +1,9 @@
-import { type PluginsCommonOptions, type CompletionAdapter } from "adminforth";
+import {
+  type PluginsCommonOptions,
+  type CompletionAdapter,
+  type AdminUser,
+  type HttpExtra,
+} from "adminforth";
 
 interface ISessionResource {
   resourceId: string;
@@ -20,6 +25,15 @@ interface ITurnResource {
 }
 
 export interface PluginOptions extends PluginsCommonOptions {
+  /**
+   * Optional placeholder examples to preload for the chat textarea.
+   * They are resolved once when the chat frontend loads.
+   */
+  placeholderMessages?: ((input: {
+    adminUser: AdminUser;
+    httpExtra: HttpExtra;
+  }) => string[] | Promise<string[]>);
+
   /**
    * Modes for the plugin.
    * Each mode can have its own configuration.
@@ -36,6 +50,11 @@ export interface PluginOptions extends PluginsCommonOptions {
    */
   maxTokens?: number;
 
+  /**
+   * Optional custom system prompt appended to the built-in agent system prompt.
+   */
+  systemPrompt?: string;
+
   /**
    * Response generation level.
    * Default is low