@adminforth/agent 2.0.10 → 2.2.0

package/dist/custom/composables/agentStore/useAgentSessions.ts

@@ -2,7 +2,7 @@ import type { ComputedRef, Ref, ShallowRef } from 'vue';
 import { callAdminForthApi } from '@/utils';
 import type { Chat } from '../../chat';
 import type { IAgentSession, ISessionsListItem, IPart } from '../../types';
-import { PRE_SESSION_ID } from './constants';
+import { PRE_SESSION_ID, STEER_PERSIST_PREFIX } from './constants';
 import { i18nInstance } from '@/i18n';
 
 type AdminforthLike = {
@@ -50,14 +50,36 @@ export function createAgentSessionManager({
 
   function saveCurrentSessionInCache() {
     if (currentSession.value) {
-      currentSession.value.messages = currentChat.value?.messages.map((m: any) => ({
-        role: m.role,
-        text: m.parts.map((p: IPart) => p.type === 'text' ? p.text : '').join(''),
-      })) || [];
+      currentSession.value.messages = currentChat.value?.messages.map((m: any) => {
+        const text = m.parts.map((p: IPart) => p.type === 'text' ? p.text : '').join('');
+        if (m.role === 'user' && m.metadata?.steer) {
+          return { role: 'user', text: `${STEER_PERSIST_PREFIX}${text}` };
+        }
+        return { role: m.role, text };
+      }) || [];
       sessions.value[currentSession.value.sessionId] = currentSession.value;
     }
   }
 
+  function mapStoredMessage(m: any): any[] {
+    if (m.role === 'user' && typeof m.text === 'string' && m.text.includes(STEER_PERSIST_PREFIX)) {
+      const [prompt, ...steers] = m.text.split(STEER_PERSIST_PREFIX);
+      const mapped: any[] = [];
+      if (prompt) {
+        mapped.push({ role: 'user', parts: [{ type: 'text', text: prompt, state: 'done' }] });
+      }
+      for (const steer of steers) {
+        mapped.push({
+          role: 'user',
+          metadata: { steer: true },
+          parts: [{ type: 'text', text: steer, state: 'done' }],
+        });
+      }
+      return mapped;
+    }
+    return [{ role: m.role, parts: [{ type: 'text', text: m.text, state: 'done' }] }];
+  }
+
   async function fetchSession(sessionId: string) {
     try {
       const res = await callAdminForthApi({
@@ -85,14 +107,7 @@ export function createAgentSessionManager({
     currentSession.value = sessions.value[sessionId];
     setCurrentChat(sessionId);
     if (currentChat.value.messages.length === 0) {
-      currentChat.value.messages = currentSession.value?.messages.map((m: any) => ({
-        role: m.role,
-        parts:[{
-          type: 'text',
-          text: m.text,
-          state: 'done',
-        }]
-      }));
+      currentChat.value.messages = currentSession.value?.messages.flatMap(mapStoredMessage);
     }
   }
 
@@ -130,8 +145,10 @@ export function createAgentSessionManager({
     }
   }
 
-  async function sendMessage() {
-    const message = trimmedUserMessage.value;
+  async function sendMessage(explicitMessage?: string) {
+    // `explicitMessage` is used to drain a buffered (queued) message; without it we send
+    // whatever is currently typed in the input.
+    const message = (explicitMessage ?? trimmedUserMessage.value).trim();
     if (!message || isMessageInputBlocked.value) {
       return;
     }
@@ -147,7 +164,9 @@ export function createAgentSessionManager({
     currentChat.value?.sendMessage({
       text: message,
     });
-    userMessageInput.value = '';
+    if (explicitMessage === undefined) {
+      userMessageInput.value = '';
+    }
   }
 
   async function createPreSession() {

package/dist/custom/composables/agentStore/useAgentSteerQueue.ts

@@ -0,0 +1,114 @@
+import type { Ref, ShallowRef } from 'vue';
+import { ref } from 'vue';
+import { callAdminForthApi } from '@/utils';
+import type { Chat } from '../../chat';
+import type { IMessage } from '../../types';
+import { PRE_SESSION_ID } from './constants';
+
+export type QueuedMessage = {
+  id: string;
+  text: string;
+};
+
+type CreateAgentSteerQueueOptions = {
+  activeSessionId: Ref<string | null>;
+  currentChat: ShallowRef<Chat<any> | null | undefined>;
+  sendMessage: (text: string) => void | Promise<void>;
+};
+
+export function createAgentSteerQueue({
+  activeSessionId,
+  currentChat,
+  sendMessage,
+}: CreateAgentSteerQueueOptions) {
+  const queue = ref<QueuedMessage[]>([]);
+
+  function enqueue(text: string) {
+    const message = text.trim();
+    if (!message) {
+      return;
+    }
+    queue.value.push({ id: crypto.randomUUID(), text: message });
+  }
+
+  function removeQueuedMessage(id: string) {
+    queue.value = queue.value.filter((item: QueuedMessage) => item.id !== id);
+  }
+
+  function injectSteerMessage(text: string) {
+    const chat = currentChat.value;
+    if (!chat) {
+      return;
+    }
+    const steerMessage: IMessage = {
+      role: 'user',
+      metadata: { steer: true },
+      parts: [{ type: 'text', text, state: 'done' }],
+    };
+    const messages = chat.messages;
+    const lastMessage = messages[messages.length - 1];
+    if (lastMessage?.role === 'assistant') {
+      messages.splice(messages.length - 1, 0, steerMessage);
+    } else {
+      messages.push(steerMessage);
+    }
+  }
+
+  // Persist the steer by appending it onto the running turn's prompt (display only — the
+  // LLM already has it via the running turn + checkpointer, so this never re-enters the
+  // model context). The backend adds the marker; the reload path splits it back out.
+  async function persistSteerMessage(sessionId: string, text: string) {
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/append-steer-to-turn',
+        body: { sessionId, message: text },
+      });
+      if (res?.error) {
+        console.error('Error persisting steer message:', res.error);
+      }
+    } catch (error) {
+      console.error('Error persisting steer message', error);
+    }
+  }
+
+  async function steerQueuedMessage(id: string) {
+    const item = queue.value.find((candidate: QueuedMessage) => candidate.id === id);
+    const sessionId = activeSessionId.value;
+    if (!item || !sessionId || sessionId === PRE_SESSION_ID) {
+      return;
+    }
+    removeQueuedMessage(id);
+    injectSteerMessage(item.text);
+    void persistSteerMessage(sessionId, item.text);
+
+    try {
+      const res = await callAdminForthApi({
+        method: 'POST',
+        path: '/agent/steer',
+        body: { sessionId, message: item.text },
+      });
+      if (res?.error) {
+        console.error('Error steering agent:', res.error);
+      }
+    } catch (error) {
+      console.error('Error steering agent', error);
+    }
+  }
+
+  function flushNext() {
+    const next = queue.value.shift();
+    if (!next) {
+      return;
+    }
+    void sendMessage(next.text);
+  }
+
+  return {
+    queue,
+    enqueue,
+    removeQueuedMessage,
+    steerQueuedMessage,
+    flushNext,
+  };
+}

package/dist/custom/composables/useAgentStore.ts

@@ -18,6 +18,7 @@ import {
 import { createAgentChatManager } from './agentStore/useAgentChat';
 import { createAgentPlaceholderController } from './agentStore/useAgentPlaceholder';
 import { createAgentSessionManager } from './agentStore/useAgentSessions';
+import { createAgentSteerQueue } from './agentStore/useAgentSteerQueue';
 
 export const useAgentStore = defineStore('agent', () => {
   const agentTransitions = useAgentTransitions();
@@ -220,6 +221,42 @@ export const useAgentStore = defineStore('agent', () => {
     setCurrentChat,
   });
 
+  // "Turn active" = a request is in flight (submitted or streaming) or paused for HITL
+  // approval. Messages submitted during this window are buffered rather than sent.
+  const isTurnActive = computed(() => {
+    const status = (currentChat.value as any)?.status;
+    return status === 'submitted' || status === 'streaming' || hasPendingToolApproval.value;
+  });
+
+  const steerBuffer = createAgentSteerQueue({
+    activeSessionId,
+    currentChat,
+    sendMessage,
+  });
+
+  // Submitting while a turn is active buffers the message (it shows up in the steer
+  // queue, where the user can steer it or let it send); otherwise it sends right away.
+  function submitUserMessage() {
+    const message = trimmedUserMessage.value;
+    if (!message) {
+      return;
+    }
+    if (isTurnActive.value) {
+      steerBuffer.enqueue(message);
+      userMessageInput.value = '';
+      return;
+    }
+    return sendMessage();
+  }
+
+  // When the active turn finishes, drain the next buffered message as a normal send
+  // (one per turn, FIFO). Messages the user explicitly steered were already removed.
+  watch(isTurnActive, (active: boolean, wasActive: boolean) => {
+    if (wasActive && !active) {
+      steerBuffer.flushNext();
+    }
+  });
+
   watch(() => viewportWidth.value, (newWidth) => {
     if (isFullScreen.value) {
       setChatWidth(newWidth, false);
@@ -505,6 +542,14 @@ export const useAgentStore = defineStore('agent', () => {
     addDataToolCallMessage,
     openAgentPage,
     setCurrentChatStatus,
-    updateLastAgentMessage
+    updateLastAgentMessage,
+    //_________-Steer queue-_____________
+    submitUserMessage,
+    isTurnActive,
+    steerQueue: steerBuffer.queue,
+    steerQueuedMessage: steerBuffer.steerQueuedMessage,
+    removeQueuedMessage: steerBuffer.removeQueuedMessage,
+    enqueueSteerMessage: steerBuffer.enqueue,
+    //___________________________________
   }
 })

package/dist/custom/conversation_area/MessageRenderer.vue

@@ -1,5 +1,11 @@
 <template>
-  <ProcessingTimeline 
+  <div
+    v-if="message.role === 'user' && message.metadata?.steer"
+    class="self-end mr-4 mb-0.5 text-xs italic text-gray-400 dark:text-gray-500"
+  >
+    {{ $t('Steering instruction') }}
+  </div>
+  <ProcessingTimeline
     :message="message"
     :isLastMessageInChat="isLastMessageInChat"
   />

package/dist/custom/speech_recognition_frontend/AudioLines.vue

@@ -11,7 +11,7 @@
 <script setup lang="ts">
 import { computed } from 'vue';
 
-const IDLE_LINE_HEIGHTS = [0.5, 1, 0.75, 0.5];
+const IDLE_LINE_HEIGHTS = [0.4, 0.8, 0.55, 0.4];
 const RECORDING_LINE_WEIGHTS = [0.45, 1, 0.75, 0.9, 0.55];
 const MIN_RECORDING_HEIGHT = 0.25;
 const MAX_RECORDING_DELTA = 0.9;

package/dist/custom/speech_recognition_frontend/MicrophoneButon.vue

@@ -1,7 +1,7 @@
 <template>
   <div
     v-show="!agentStore.isResponseInProgress || isAudioChatMode"
-    class="absolute bottom-2 flex items-center justify-center z-10 gap-4"
+    class="absolute bottom-1 flex items-center justify-center z-10 gap-4"
     :class="[!agentStore.isAudioChatMode ? 'right-16': agentStore.isMobile ? 'right-1/2 translate-x-1/2' : 'right-1/2 translate-x-1/2']"
   > 
     <button 
@@ -14,10 +14,10 @@
     </button>
     <button
       v-else 
-      class="h-9 bg-lightPrimary dark:bg-darkPrimary 
+      class="h-7 bg-lightPrimary dark:bg-darkPrimary 
         hover:opacity-90 rounded-full flex items-center justify-center
         transition-all duration-300 ease-in-out overflow-hidden"
-      :class="[isAudioChatMode ? 'w-32 px-2': 'w-9']" 
+      :class="[isAudioChatMode ? 'w-32 px-2': 'w-7']" 
       @click="toggleChatMode"
     >
       <div class="w-5 h-5 flex items-center justify-center">

package/dist/{agentEvents.d.ts → domain/agentEvents.d.ts}

@@ -1,4 +1,4 @@
-import type { ToolCallEvent } from "./agent/toolCallEvents.js";
+import type { ToolCallEvent } from "./toolCallEvents.js";
 export type AgentEvent = {
     type: "turn-started";
     messageId: string;
@@ -19,6 +19,10 @@ export type AgentEvent = {
     type: "interrupt";
     sessionId: string;
     interrupt: unknown;
+} | {
+    type: "steer-applied";
+    count: number;
+    ids: string[];
 } | {
     type: "open-page";
     targetPath: string;

package/dist/domain/steerBuffer.d.ts

@@ -0,0 +1,33 @@
+/** A single steering instruction the user sent while a turn was already running. */
+export type SteerMessage = {
+    id: string;
+    text: string;
+    /** Epoch ms the steer was enqueued; useful for ordering/debugging. */
+    at: number;
+};
+/**
+ * In-process, per-session buffer of steering instructions.
+ *
+ * While an agent turn is streaming (thinking / calling tools) the user may send
+ * one or more extra instructions ("steers"). Each is enqueued here by the
+ * `/agent/steer` endpoint and drained by the `beforeModel` steer middleware just
+ * before the next model call in the same running loop, so the model course-corrects
+ * mid-turn instead of the user having to abort and restart.
+ *
+ * The buffer is deliberately in-process: a steer only makes sense for a turn that
+ * is *currently running*, and that turn's SSE stream is held open on exactly one
+ * instance/process. In a multi-instance deployment the `/agent/steer` request must
+ * therefore reach the same instance running the turn (same constraint the in-memory
+ * HITL cache / MemorySaver already carry when no persistent checkpointer is set).
+ */
+export declare class SteerBuffer {
+    private readonly buffers;
+    /** Enqueue a steering instruction for a session. Returns the created entry. */
+    add(sessionId: string, text: string): SteerMessage;
+    /** Number of steers currently buffered for a session. */
+    size(sessionId: string): number;
+    /** Return every buffered steer for a session and remove them from the buffer. */
+    drain(sessionId: string): SteerMessage[];
+    /** Discard any buffered steers for a session (e.g. when its turn ends unconsumed). */
+    clear(sessionId: string): void;
+}

package/dist/domain/steerBuffer.js

@@ -0,0 +1,51 @@
+import { randomUUID } from "crypto";
+/**
+ * In-process, per-session buffer of steering instructions.
+ *
+ * While an agent turn is streaming (thinking / calling tools) the user may send
+ * one or more extra instructions ("steers"). Each is enqueued here by the
+ * `/agent/steer` endpoint and drained by the `beforeModel` steer middleware just
+ * before the next model call in the same running loop, so the model course-corrects
+ * mid-turn instead of the user having to abort and restart.
+ *
+ * The buffer is deliberately in-process: a steer only makes sense for a turn that
+ * is *currently running*, and that turn's SSE stream is held open on exactly one
+ * instance/process. In a multi-instance deployment the `/agent/steer` request must
+ * therefore reach the same instance running the turn (same constraint the in-memory
+ * HITL cache / MemorySaver already carry when no persistent checkpointer is set).
+ */
+export class SteerBuffer {
+    constructor() {
+        this.buffers = new Map();
+    }
+    /** Enqueue a steering instruction for a session. Returns the created entry. */
+    add(sessionId, text) {
+        const message = { id: randomUUID(), text, at: Date.now() };
+        const existing = this.buffers.get(sessionId);
+        if (existing) {
+            existing.push(message);
+        }
+        else {
+            this.buffers.set(sessionId, [message]);
+        }
+        return message;
+    }
+    /** Number of steers currently buffered for a session. */
+    size(sessionId) {
+        var _a, _b;
+        return (_b = (_a = this.buffers.get(sessionId)) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0;
+    }
+    /** Return every buffered steer for a session and remove them from the buffer. */
+    drain(sessionId) {
+        const messages = this.buffers.get(sessionId);
+        if (!messages || messages.length === 0) {
+            return [];
+        }
+        this.buffers.delete(sessionId);
+        return messages;
+    }
+    /** Discard any buffered steers for a session (e.g. when its turn ends unconsumed). */
+    clear(sessionId) {
+        this.buffers.delete(sessionId);
+    }
+}

package/dist/{agent → domain}/systemPrompt.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { listProjectSkillManifests, } from "./skills/registry.js";
+import { listProjectSkillManifests, } from "../tools/skills/registry.js";
 export const DEFAULT_AGENT_SYSTEM_PROMPT = [
     "You are helpful AI Assistant for Admin Panel.",
     // about admin

package/dist/{agent/turn → domain}/turnTypes.d.ts

@@ -1,11 +1,21 @@
 import type { AdminUser, AudioAdapter } from "adminforth";
-import type { Messages } from "@langchain/langgraph";
-import type { Command } from "@langchain/langgraph";
-import type { AgentChatModel, AgentMiddleware } from "../simpleAgent.js";
-import type { SequenceDebugCollector } from "../middleware/sequenceDebug.js";
-import type { PreviousUserMessage } from "../languageDetect.js";
 import type { CurrentPageContext } from "../tools/getUserLocation.js";
-import type { AgentEventEmitter } from "../../agentEvents.js";
+import type { AgentEventEmitter } from "./agentEvents.js";
+/**
+ * Minimal sink the application layer uses to persist per-turn debug traces. The
+ * concrete implementation (the sequence-debug collector) lives in the llm layer;
+ * the domain/application layers depend only on this narrow interface, so the
+ * dependency direction stays llm -> application/domain.
+ */
+export type DebugSink = {
+    flush(): void;
+    getHistory(): unknown[];
+};
+/** A pending human-in-the-loop approval, normalized (provider-agnostic). */
+export type PendingInterrupt = {
+    id: string;
+    count: number;
+};
 export type BaseAgentTurnInput = {
     prompt: string;
     sessionId: string;
@@ -46,37 +56,7 @@ export type AgentTurnContext = {
 };
 export type AgentTurnObservability = {
     emit?: AgentEventEmitter;
-    sequenceDebugSink: SequenceDebugCollector;
-};
-export type PreparedAgentTurn = {
-    prompt: string;
-    sessionId: string;
-    turnId: string;
-    previousUserMessages: PreviousUserMessage[];
-    modeName?: string | null;
-    context: AgentTurnContext;
-    observability: AgentTurnObservability;
-    resume?: {
-        decision: "approve" | "reject";
-        interrupts?: {
-            id: string;
-            count: number;
-        }[];
-    };
-    initialResponse?: string;
-};
-export type AgentTurnModels = {
-    model: AgentChatModel;
-    summaryModel: AgentChatModel;
-    modelMiddleware?: AgentMiddleware[];
-};
-export type AgentRuntimeRunInput = {
-    models: AgentTurnModels;
-    input: {
-        messages: Messages;
-    } | Command;
-    context: AgentTurnContext;
-    observability: AgentTurnObservability;
+    sequenceDebugSink: DebugSink;
 };
 export type RunAndPersistAgentResponseInput = BaseAgentTurnInput & {
     emit?: AgentEventEmitter;
@@ -92,3 +72,27 @@ export type RunAndPersistAgentResponseResult = {
 };
 export type HandleTurnInput = TextAgentTurnInput;
 export type HandleSpeechTurnInput = SpeechAgentTurnInput;
+/**
+ * Provider-agnostic message passed from the application layer to the LLM port.
+ * The infrastructure adapter maps it onto concrete LangChain messages.
+ */
+export type AgentMessage = {
+    role: "system" | "user";
+    content: string;
+};
+/**
+ * Normalized unit of a streamed agent turn. The LLM port converts the raw
+ * LangGraph stream into these typed chunks so the application layer never
+ * touches LangGraph's tuple/`any` stream shape.
+ */
+export type AgentStreamChunk = {
+    kind: "text";
+    delta: string;
+} | {
+    kind: "reasoning";
+    delta: string;
+} | {
+    kind: "interrupt";
+    interrupt: unknown;
+    descriptors: PendingInterrupt[];
+};

package/dist/{agent/turn/VegaLiteStreamBuffer.d.ts → domain/vegaLiteStreamBuffer.d.ts}

@@ -1,4 +1,4 @@
-import type { AgentEventEmitter } from "../../agentEvents.js";
+import type { AgentEventEmitter } from "./agentEvents.js";
 export declare class VegaLiteStreamBuffer {
     private bufferedTextDelta;
     private isRenderingVegaLite;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { AdminForthResource, IAdminForth, IHttpServer } from "adminforth";
 import { AdminForthPlugin } from "adminforth";
 import type { PluginOptions } from './types.js';
-export type { AgentEvent, AgentEventEmitter } from "./agentEvents.js";
+export type { AgentEvent, AgentEventEmitter } from "./domain/agentEvents.js";
 export default class AdminForthAgentPlugin extends AdminForthPlugin {
     options: PluginOptions;
     agentSystemPromptPromise: Promise<string>;
@@ -9,11 +9,13 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     private agentSystemPrompt;
     private checkpointer;
     private sessionStore;
-    private agentTurnService;
+    private steerBuffer;
+    private runTurnUseCase;
     private speechTurnService;
     private chatSurfaceService;
     private getCheckpointer;
     private getInternalAgentResourceIds;
+    private getAgentSystemPrompt;
     constructor(options: PluginOptions);
     modifyGlobalConfig(adminforth: IAdminForth): Promise<void>;
     validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource): void;