@adminforth/agent 1.50.0 → 1.51.0

package/agentTurnService.ts

@@ -1,298 +1,102 @@
-import type { AdminUser, AudioAdapter, IAdminForth } from "adminforth";
 import { logger } from "adminforth";
 import { randomUUID } from "crypto";
-import { HumanMessage, SystemMessage } from "langchain";
-import type { BaseCheckpointSaver } from "@langchain/langgraph";
-import { createAgentChatModel, callAgent } from "./agent/simpleAgent.js";
+import { AgentModelFactory } from "./agent/models/AgentModelFactory.js";
+import { AgentModeResolver } from "./agent/models/AgentModeResolver.js";
 import { createSequenceDebugCollector } from "./agent/middleware/sequenceDebug.js";
-import { detectUserLanguage, type PreviousUserMessage } from "./agent/languageDetect.js";
-import { prepareApiBasedTools as buildApiBasedTools } from "./apiBasedTools.js";
-import type { AgentEventEmitter } from "./agentEvents.js";
-import { buildAgentTurnSystemPrompt } from "./agent/systemPrompt.js";
-import type { CurrentPageContext } from "./agent/tools/getUserLocation.js";
-import { isAbortError, getErrorMessage } from "./errors.js";
-import { sanitizeSpeechText } from "./sanitizeSpeechText.js";
-import type { AgentSessionStore } from "./sessionStore.js";
-import type { PluginOptions } from "./types.js";
-
-type AgentTurnRunInput = {
-  prompt: string;
-  sessionId: string;
-  turnId: string;
-  previousUserMessages: PreviousUserMessage[];
-  modeName?: string | null;
-  userTimeZone: string;
-  currentPage?: CurrentPageContext;
-  chatSurface?: string;
-  adminPublicOrigin?: string;
-  abortSignal?: AbortSignal;
-  adminUser: AdminUser;
-  sequenceDebugCollector: ReturnType<typeof createSequenceDebugCollector>;
-  emit?: AgentEventEmitter;
-};
-
-export type RunAndPersistAgentResponseInput = {
-  prompt: string;
-  sessionId: string;
-  modeName?: string | null;
-  userTimeZone: string;
-  currentPage?: CurrentPageContext;
-  chatSurface?: string;
-  adminPublicOrigin?: string;
-  abortSignal?: AbortSignal;
-  adminUser: AdminUser;
-  emit?: AgentEventEmitter;
-  failureLogMessage: string;
-  abortLogMessage: string;
-};
-
-export type RunAndPersistAgentResponseResult = {
-  text: string;
-  turnId: string;
-  aborted: boolean;
-  failed: boolean;
-};
-
-export type HandleTurnInput = Omit<RunAndPersistAgentResponseInput, "failureLogMessage" | "abortLogMessage"> & {
-  emit: AgentEventEmitter;
-  failureLogMessage?: string;
-  abortLogMessage?: string;
-};
-
-export type HandleSpeechTurnInput = Omit<HandleTurnInput, "prompt"> & {
-  audioAdapter: AudioAdapter;
-  audio: {
-    buffer: Buffer;
-    filename: string;
-    mimeType: string;
-  };
-};
-
-type AgentTurnServiceOptions = {
-  getAdminforth: () => IAdminForth;
-  getPluginInstanceId: () => string;
-  options: PluginOptions;
-  sessionStore: AgentSessionStore;
-  getCheckpointer: () => BaseCheckpointSaver;
-  getInternalAgentResourceIds: () => string[];
-  getAgentSystemPrompt: () => Promise<string>;
-};
-
-const VEGA_LITE_FENCE_START = "```vega-lite";
-const COMPLETE_VEGA_LITE_BLOCK_RE = /```vega-lite[\s\S]*?```/;
+import { AgentRuntime } from "./agent/runtime/AgentRuntime.js";
+import { TurnContextBuilder } from "./agent/turn/TurnContextBuilder.js";
+import { TurnLifecycleService } from "./agent/turn/TurnLifecycleService.js";
+import { TurnPromptBuilder } from "./agent/turn/TurnPromptBuilder.js";
+import { TurnStreamConsumer } from "./agent/turn/TurnStreamConsumer.js";
+import type {
+  BaseAgentTurnInput,
+  HandleTurnInput,
+  PreparedAgentTurn,
+  RunAndPersistAgentResponseInput,
+  RunAndPersistAgentResponseResult,
+} from "./agent/turn/turnTypes.js";
+import { getErrorMessage, isAbortError } from "./errors.js";
+
+export type {
+  BaseAgentTurnInput,
+  HandleSpeechTurnInput,
+  HandleTurnInput,
+  RunAndPersistAgentResponseInput,
+  RunAndPersistAgentResponseResult,
+} from "./agent/turn/turnTypes.js";
 
 export class AgentTurnService {
-  constructor(private serviceOptions: AgentTurnServiceOptions) {}
-
-  private async runAgentTurn(input: AgentTurnRunInput) {
-    const adminforth = this.serviceOptions.getAdminforth();
-    const options = this.serviceOptions.options;
-    let fullResponse = "";
-    let bufferedTextDelta = "";
-    let isRenderingVegaLite = false;
-    const maxTokens = options.maxTokens ?? 1000;
-    const selectedMode = options.modes.find((mode) => mode.name === input.modeName) ?? options.modes[0];
-    const [primaryModelSpec, summaryModelSpec] = await Promise.all([
-      createAgentChatModel({
-        adapter: selectedMode.completionAdapter,
-        maxTokens,
-        purpose: "primary",
-      }),
-      createAgentChatModel({
-        adapter: selectedMode.completionAdapter,
-        maxTokens,
-        purpose: "summary",
-      }),
-    ]);
-    const model = primaryModelSpec.model;
-    const summaryModel = summaryModelSpec.model;
-    const modelMiddleware = primaryModelSpec.middleware;
-
-    const userLanguage = await detectUserLanguage(selectedMode.completionAdapter, input.prompt, input.previousUserMessages)
-      .catch((error) => {
-        if (input.abortSignal?.aborted || isAbortError(error)) {
-          throw error;
-        }
-
-        logger.warn(`Failed to detect user language: ${getErrorMessage(error)}`);
-        return null;
-      });
-    const systemPrompt = buildAgentTurnSystemPrompt({
-      agentSystemPrompt: await this.serviceOptions.getAgentSystemPrompt(),
-      adminUser: input.adminUser,
-      usernameField: adminforth.config.auth!.usernameField,
-      userLanguage,
-      chatSurface: input.chatSurface,
+  constructor(
+    private readonly lifecycle: TurnLifecycleService,
+    private readonly contextBuilder: TurnContextBuilder,
+    private readonly modeResolver: AgentModeResolver,
+    private readonly modelFactory: AgentModelFactory,
+    private readonly promptBuilder: TurnPromptBuilder,
+    private readonly runtime: AgentRuntime,
+    private readonly streamConsumer: TurnStreamConsumer,
+  ) {}
+
+  private async prepareTurn(input: BaseAgentTurnInput): Promise<PreparedAgentTurn> {
+    const sequenceDebugCollector = createSequenceDebugCollector();
+    const { turnId, previousUserMessages } = await this.lifecycle.start(input);
+    const context = await this.contextBuilder.build({
+      base: input,
+      turnId,
     });
-    const apiBasedTools = buildApiBasedTools(
-      adminforth,
-      this.serviceOptions.getInternalAgentResourceIds(),
-    );
 
-    const stream = await callAgent({
-      name: `adminforth-agent-${this.serviceOptions.getPluginInstanceId()}`,
-      model,
-      summaryModel,
-      modelMiddleware,
-      checkpointer: this.serviceOptions.getCheckpointer(),
-      messages: [
-        new SystemMessage(systemPrompt),
-        new HumanMessage(input.prompt),
-      ],
-      adminUser: input.adminUser,
-      adminforth,
-      apiBasedTools,
-      customComponentsDir: adminforth.config.customization.customComponentsDir ?? "custom",
-      pluginCustomFolderPaths: adminforth.activatedPlugins.map((plugin) => plugin.customFolderPath),
+    return {
+      prompt: input.prompt,
       sessionId: input.sessionId,
-      turnId: input.turnId,
-      currentPage: input.currentPage,
-      chatSurface: input.chatSurface,
-      adminPublicOrigin: input.adminPublicOrigin,
-      userTimeZone: input.userTimeZone,
-      abortSignal: input.abortSignal,
-      emitToolCallEvent: (event) => {
-        input.sequenceDebugCollector.handleToolCallEvent(event);
-        void input.emit?.({
-          type: "tool-call",
-          data: event,
-        });
+      turnId,
+      previousUserMessages,
+      modeName: input.modeName,
+      context,
+      observability: {
+        emit: undefined,
+        sequenceDebugSink: sequenceDebugCollector,
       },
-      emitAgentEvent: input.emit,
-      sequenceDebugSink: input.sequenceDebugCollector,
-    });
-
-    for await (const rawChunk of stream as AsyncIterable<[any, any]>) {
-      if (input.abortSignal?.aborted) {
-        throw new DOMException("This operation was aborted", "AbortError");
-      }
-
-      const [token, metadata] = rawChunk;
-
-      const nodeName =
-        typeof metadata?.langgraph_node === "string"
-          ? metadata.langgraph_node
-          : "";
-
-      if (nodeName && !["model", "model_request"].includes(nodeName)) {
-        continue;
-      }
-
-      const blocks = Array.isArray(token?.contentBlocks)
-        ? token.contentBlocks
-        : Array.isArray(token?.content)
-          ? token.content
-          : [];
-      const reasoningDelta = blocks
-        .filter((b: any) => b?.type === "reasoning")
-        .map((b: any) => String(b.reasoning ?? ""))
-        .join("");
-
-      const textDelta = blocks
-        .filter((b: any) => b?.type === "text")
-        .map((b: any) => String(b.text ?? ""))
-        .join("");
-
-      if (reasoningDelta) {
-        await input.emit?.({
-          type: "reasoning-delta",
-          delta: reasoningDelta,
-        });
-      }
-
-      if (textDelta) {
-        fullResponse += textDelta;
-        bufferedTextDelta += textDelta;
-
-        if (
-          bufferedTextDelta.includes(VEGA_LITE_FENCE_START) &&
-          !COMPLETE_VEGA_LITE_BLOCK_RE.test(bufferedTextDelta)
-        ) {
-          if (!isRenderingVegaLite) {
-            isRenderingVegaLite = true;
-            await input.emit?.({
-              type: "rendering",
-              phase: "start",
-              label: "Rendering...",
-            });
-          }
-          continue;
-        }
-
-        if (isRenderingVegaLite) {
-          isRenderingVegaLite = false;
-          await input.emit?.({
-            type: "rendering",
-            phase: "end",
-            label: "Rendering...",
-          });
-        }
-
-        const streamableLength = bufferedTextDelta.includes(VEGA_LITE_FENCE_START)
-          ? bufferedTextDelta.length
-          : bufferedTextDelta.length - getPartialVegaLiteFenceStartLength(bufferedTextDelta);
-
-        if (!streamableLength) {
-          continue;
-        }
-
-        await input.emit?.({
-          type: "text-delta",
-          delta: bufferedTextDelta.slice(0, streamableLength),
-        });
-        bufferedTextDelta = bufferedTextDelta.slice(streamableLength);
-      }
-    }
-
-    if (isRenderingVegaLite) {
-      await input.emit?.({
-        type: "rendering",
-        phase: "end",
-        label: "Rendering...",
-      });
-    }
-
-    if (bufferedTextDelta) {
-      await input.emit?.({
-        type: "text-delta",
-        delta: bufferedTextDelta,
-      });
-    }
-
-    return {
-      text: fullResponse,
     };
   }
 
-  async runAndPersistAgentResponse(input: RunAndPersistAgentResponseInput) {
-    const adminforth = this.serviceOptions.getAdminforth();
-    const options = this.serviceOptions.options;
-    const previousUserMessages = await this.serviceOptions.sessionStore.getPreviousUserMessages(input.sessionId);
-    const turnId = await this.serviceOptions.sessionStore.createNewTurn(input.sessionId, input.prompt);
-    await adminforth.resource(options.sessionResource.resourceId).update(input.sessionId, {
-      [options.sessionResource.createdAtField]: new Date().toISOString(),
+  private async runAgentTurn(input: PreparedAgentTurn) {
+    const selectedMode = this.modeResolver.resolve(input.modeName);
+    const [models, messages] = await Promise.all([
+      this.modelFactory.create(selectedMode.completionAdapter),
+      this.promptBuilder.build({
+        prompt: input.prompt,
+        previousUserMessages: input.previousUserMessages,
+        adminUser: input.context.adminUser,
+        completionAdapter: selectedMode.completionAdapter,
+        chatSurface: input.context.chatSurface,
+        abortSignal: input.context.abortSignal,
+      }),
+    ]);
+    const stream = await this.runtime.stream({
+      models,
+      messages,
+      context: input.context,
+      observability: input.observability,
     });
-    const sequenceDebugCollector = createSequenceDebugCollector();
+
+    return this.streamConsumer.consume({
+      stream: stream as AsyncIterable<[any, any]>,
+      abortSignal: input.context.abortSignal,
+      emit: input.observability.emit,
+    });
+  }
+
+  async runAndPersistAgentResponse(
+    input: RunAndPersistAgentResponseInput,
+  ): Promise<RunAndPersistAgentResponseResult> {
+    const preparedTurn = await this.prepareTurn(input);
+    preparedTurn.observability.emit = input.emit;
+
     let fullResponse = "";
     let aborted = false;
     let failed = false;
 
     try {
-      const agentResponse = await this.runAgentTurn({
-        prompt: input.prompt,
-        sessionId: input.sessionId,
-        turnId,
-        previousUserMessages,
-        modeName: input.modeName,
-        userTimeZone: input.userTimeZone,
-        currentPage: input.currentPage,
-        chatSurface: input.chatSurface,
-        adminPublicOrigin: input.adminPublicOrigin,
-        abortSignal: input.abortSignal,
-        adminUser: input.adminUser,
-        sequenceDebugCollector,
-        emit: input.emit,
-      });
+      const agentResponse = await this.runAgentTurn(preparedTurn);
       fullResponse = agentResponse.text;
     } catch (error) {
       if (input.abortSignal?.aborted || isAbortError(error)) {
@@ -305,20 +109,16 @@ export class AgentTurnService {
       }
     }
 
-    sequenceDebugCollector.flush();
-    const turnUpdates: Record<string, unknown> = {
-      [options.turnResource.responseField]: fullResponse,
-    };
-
-    if (options.turnResource.debugField) {
-      turnUpdates[options.turnResource.debugField] = sequenceDebugCollector.getHistory();
-    }
-
-    await adminforth.resource(options.turnResource.resourceId).update(turnId, turnUpdates);
+    preparedTurn.observability.sequenceDebugSink.flush();
+    await this.lifecycle.finish({
+      turnId: preparedTurn.turnId,
+      responseText: fullResponse,
+      debugHistory: preparedTurn.observability.sequenceDebugSink.getHistory(),
+    });
 
     return {
       text: fullResponse,
-      turnId,
+      turnId: preparedTurn.turnId,
       aborted,
       failed,
     };
@@ -365,177 +165,4 @@ export class AgentTurnService {
 
     return agentResponse;
   }
-
-  async handleSpeechTurn(input: HandleSpeechTurnInput) {
-    let transcription;
-
-    try {
-      transcription = await input.audioAdapter.transcribe({
-        buffer: input.audio.buffer,
-        filename: input.audio.filename,
-        mimeType: input.audio.mimeType,
-        language: "auto",
-        abortSignal: input.abortSignal,
-      });
-    } catch (error) {
-      if (input.abortSignal?.aborted || isAbortError(error)) {
-        logger.info("Agent speech transcription aborted by the client");
-        await input.emit({ type: "finish" });
-        return null;
-      }
-
-      logger.error(`Agent speech transcription failed:\n${getErrorMessage(error)}`);
-      await input.emit({
-        type: "error",
-        error: "Speech transcription failed. Check server logs for details.",
-      });
-      await input.emit({ type: "finish" });
-      return null;
-    }
-
-    if (input.abortSignal?.aborted) {
-      await input.emit({ type: "finish" });
-      return null;
-    }
-
-    const prompt = transcription.text;
-    if (!prompt) {
-      await input.emit({
-        type: "error",
-        error: "Speech transcription is empty",
-      });
-      await input.emit({ type: "finish" });
-      return null;
-    }
-
-    await input.emit({
-      type: "transcript",
-      text: transcription.text,
-      language: transcription.language,
-    });
-
-    const agentResponse = await this.runAndPersistAgentResponse({
-      prompt,
-      sessionId: input.sessionId,
-      modeName: input.modeName,
-      userTimeZone: input.userTimeZone,
-      currentPage: input.currentPage,
-      chatSurface: input.chatSurface,
-      adminPublicOrigin: input.adminPublicOrigin,
-      abortSignal: input.abortSignal,
-      adminUser: input.adminUser,
-      emit: async (event) => {
-        if (event.type === "tool-call") {
-          await input.emit(event);
-        }
-      },
-      failureLogMessage: input.failureLogMessage ?? "Agent speech response failed",
-      abortLogMessage: input.abortLogMessage ?? "Agent speech response aborted by the client",
-    });
-
-    if (agentResponse.aborted) {
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    }
-
-    if (agentResponse.failed) {
-      await input.emit({
-        type: "error",
-        error: agentResponse.text,
-      });
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    }
-
-    try {
-      await input.emit({
-        type: "speech-response",
-        transcript: {
-          text: transcription.text,
-          language: transcription.language,
-        },
-        response: {
-          text: agentResponse.text,
-        },
-        sessionId: input.sessionId,
-        turnId: agentResponse.turnId,
-      });
-      const speech = await input.audioAdapter.synthesize({
-        text: sanitizeSpeechText(agentResponse.text),
-        stream: true,
-        streamFormat: "audio",
-        format: "pcm",
-        abortSignal: input.abortSignal,
-      });
-
-      await input.emit({
-        type: "audio-start",
-        mimeType: speech.mimeType,
-        format: speech.format,
-        sampleRate: 24000,
-        channelCount: 1,
-        bitsPerSample: 16,
-      });
-
-      const reader = speech.audioStream.getReader();
-      const cancelAudioStream = () => {
-        void reader.cancel().catch(() => undefined);
-      };
-
-      try {
-        input.abortSignal?.addEventListener("abort", cancelAudioStream, { once: true });
-
-        while (true) {
-          if (input.abortSignal?.aborted) {
-            await reader.cancel().catch(() => undefined);
-            break;
-          }
-
-          const { value, done } = await reader.read();
-
-          if (done) {
-            break;
-          }
-
-          if (input.abortSignal?.aborted) {
-            break;
-          }
-
-          await input.emit({
-            type: "audio-delta",
-            value,
-          });
-        }
-      } finally {
-        input.abortSignal?.removeEventListener("abort", cancelAudioStream);
-        reader.releaseLock();
-      }
-
-      await input.emit({ type: "audio-done" });
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    } catch (error) {
-      if (input.abortSignal?.aborted || isAbortError(error)) {
-        logger.info("Agent speech audio streaming aborted by the client");
-      } else {
-        logger.error(`Agent speech audio streaming failed:\n${getErrorMessage(error)}`);
-        await input.emit({
-          type: "error",
-          error: getErrorMessage(error),
-        });
-      }
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    }
-  }
-}
-
-function getPartialVegaLiteFenceStartLength(text: string): number {
-  for (let length = Math.min(text.length, VEGA_LITE_FENCE_START.length - 1); length > 0; length -= 1) {
-    if (VEGA_LITE_FENCE_START.startsWith(text.slice(-length))) {
-      return length;
-    }
-  }
-
-  return 0;
 }

package/build.log

@@ -62,5 +62,5 @@ custom/speech_recognition_frontend/voiceActivityDetection.ts
 custom/speech_recognition_frontend/types/
 custom/speech_recognition_frontend/types/voice-activity-detection.d.ts
 
-sent 1,670,250 bytes  received 921 bytes  3,342,342.00 bytes/sec
-total size is 1,666,155  speedup is 1.00
+sent 1,670,939 bytes  received 917 bytes  3,343,712.00 bytes/sec
+total size is 1,666,790  speedup is 1.00

package/custom/skills/fetch_data/SKILL.md

@@ -24,6 +24,8 @@ If several rows look similar, do not guess which one is "the same" record. Show
 
 For long texts show only several first words and add "..." at the end (only if user did not request this field specifically).
 
+Never show information about more than 10 records in one message. If a tool returns more than 10 relevant records, summarize the total count if known, show only the 10 most relevant records, and offer to narrow filters, sort differently, or continue with the next 10.
+
 Also when you communicate with user about record, add related link to this record. Build it as `{ADMIN_BASE_PATH}resource/{resourceId}/show/{primary key}`. Use _label from `get_resource_data` as anchor text for link (use markdown link). Links should always be relative paths and must start with `ADMIN_BASE_PATH`. Do not add an extra slash after `ADMIN_BASE_PATH`.
 
 Before sending the link, verify that the `resourceId`, `{primary key}`, `_label`, and shown fields come from the same exact returned row.

package/custom/skills/mutate_data/SKILL.md

@@ -27,6 +27,8 @@ Also please add related link to record with will be changed. Build it as `{ADMIN
 
 Before sending the confirmation, verify that the `resourceId`, `{primary key}`, `_label`, and all shown fields come from the same exact fetched row.
 
+Never show information about more than 10 records in one message. If a mutation plan affects more than 10 records, show only the 10 most important examples plus the total count if known, and ask the user to confirm the clearly described full batch.
+
 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.
@@ -123,6 +125,8 @@ 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.
 
+If more than 10 records were created, show links or details for only 10 of them and summarize the remaining count.
+
 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.
 
 ### Working with dates 

package/dist/agent/middleware/apiBasedTools.js

@@ -65,7 +65,14 @@ export function createApiBasedToolsMiddleware(apiBasedTools, adminforth) {
                 var _a, _b, _c, _d;
                 const startedAt = Date.now();
                 const toolInput = JSON.stringify((_a = request.toolCall.args) !== null && _a !== void 0 ? _a : {});
-                const { adminUser, emitToolCallEvent, userTimeZone } = request.runtime.context;
+                const { adminUser, emit, sequenceDebugSink, userTimeZone } = request.runtime.context;
+                const emitToolCall = (event) => {
+                    sequenceDebugSink.handleToolCallEvent(event);
+                    void (emit === null || emit === void 0 ? void 0 : emit({
+                        type: "tool-call",
+                        data: event,
+                    }));
+                };
                 const toolArgs = ((_b = request.toolCall.args) !== null && _b !== void 0 ? _b : {});
                 let toolInfo;
                 if (request.toolCall.name === "fetch_skill") {
@@ -84,7 +91,7 @@ export function createApiBasedToolsMiddleware(apiBasedTools, adminforth) {
                     });
                 }
                 const toolCallTracker = createToolCallTracker({
-                    emit: emitToolCallEvent,
+                    emit: emitToolCall,
                     toolCallId: request.toolCall.id,
                     toolName: request.toolCall.name,
                     toolInfo,

package/dist/agent/models/AgentModeResolver.d.ts

@@ -0,0 +1,9 @@
+import type { PluginOptions } from "../../types.js";
+export declare class AgentModeResolver {
+    private readonly options;
+    constructor(options: PluginOptions);
+    resolve(modeName?: string | null): {
+        name: string;
+        completionAdapter: import("../simpleAgent.js").AgentModeCompletionAdapter;
+    };
+}

package/dist/agent/models/AgentModeResolver.js

@@ -0,0 +1,9 @@
+export class AgentModeResolver {
+    constructor(options) {
+        this.options = options;
+    }
+    resolve(modeName) {
+        var _a;
+        return (_a = this.options.modes.find((mode) => mode.name === modeName)) !== null && _a !== void 0 ? _a : this.options.modes[0];
+    }
+}

package/dist/agent/models/AgentModelFactory.d.ts

@@ -0,0 +1,7 @@
+import type { CompletionAdapter } from "adminforth";
+import type { AgentTurnModels } from "../turn/turnTypes.js";
+export declare class AgentModelFactory {
+    private readonly maxTokens;
+    constructor(maxTokens: number);
+    create(completionAdapter: CompletionAdapter): Promise<AgentTurnModels>;
+}