@adminforth/agent 1.50.1 → 1.51.0

package/agent/turn/TurnPromptBuilder.ts

@@ -0,0 +1,51 @@
+import type { AdminUser, IAdminForth } from "adminforth";
+import { logger } from "adminforth";
+import { HumanMessage, SystemMessage } from "langchain";
+import { detectUserLanguage, type PreviousUserMessage } from "../languageDetect.js";
+import { buildAgentTurnSystemPrompt } from "../systemPrompt.js";
+import { getErrorMessage, isAbortError } from "../../errors.js";
+import type { AgentModeCompletionAdapter } from "../simpleAgent.js";
+
+export class TurnPromptBuilder {
+  constructor(
+    private readonly options: {
+      getAgentSystemPrompt: () => Promise<string>;
+      getAdminforth: () => IAdminForth;
+    },
+  ) {}
+
+  async build(input: {
+    prompt: string;
+    previousUserMessages: PreviousUserMessage[];
+    adminUser: AdminUser;
+    completionAdapter: AgentModeCompletionAdapter;
+    chatSurface?: string;
+    abortSignal?: AbortSignal;
+  }) {
+    const adminforth = this.options.getAdminforth();
+    const userLanguage = await detectUserLanguage(
+      input.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.options.getAgentSystemPrompt(),
+      adminUser: input.adminUser,
+      usernameField: adminforth.config.auth!.usernameField,
+      userLanguage,
+      chatSurface: input.chatSurface,
+    });
+
+    return [
+      new SystemMessage(systemPrompt),
+      new HumanMessage(input.prompt),
+    ];
+  }
+}

package/agent/turn/TurnStreamConsumer.ts

@@ -0,0 +1,61 @@
+import type { AgentEventEmitter } from "../../agentEvents.js";
+import { VegaLiteStreamBuffer } from "./VegaLiteStreamBuffer.js";
+
+export class TurnStreamConsumer {
+  async consume(input: {
+    stream: AsyncIterable<[any, any]>;
+    abortSignal?: AbortSignal;
+    emit?: AgentEventEmitter;
+  }) {
+    let fullResponse = "";
+    const textBuffer = new VegaLiteStreamBuffer();
+
+    for await (const rawChunk of input.stream) {
+      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((block: any) => block?.type === "reasoning")
+        .map((block: any) => String(block.reasoning ?? ""))
+        .join("");
+      const textDelta = blocks
+        .filter((block: any) => block?.type === "text")
+        .map((block: any) => String(block.text ?? ""))
+        .join("");
+
+      if (reasoningDelta) {
+        await input.emit?.({
+          type: "reasoning-delta",
+          delta: reasoningDelta,
+        });
+      }
+
+      if (textDelta) {
+        fullResponse += textDelta;
+        await textBuffer.push(textDelta, input.emit);
+      }
+    }
+
+    await textBuffer.flush(input.emit);
+
+    return {
+      text: fullResponse,
+    };
+  }
+}

package/agent/turn/VegaLiteStreamBuffer.ts

@@ -0,0 +1,90 @@
+import type { AgentEventEmitter } from "../../agentEvents.js";
+
+const VEGA_LITE_FENCE_START = "```vega-lite";
+const FENCE_END = "```";
+
+export class VegaLiteStreamBuffer {
+  private bufferedTextDelta = "";
+  private isRenderingVegaLite = false;
+
+  async push(textDelta: string, emit?: AgentEventEmitter) {
+    this.bufferedTextDelta += textDelta;
+
+    if (
+      hasUnclosedLatestVegaLiteBlock(this.bufferedTextDelta)
+    ) {
+      if (!this.isRenderingVegaLite) {
+        this.isRenderingVegaLite = true;
+        await emit?.({
+          type: "rendering",
+          phase: "start",
+          label: "Rendering...",
+        });
+      }
+      return;
+    }
+
+    if (this.isRenderingVegaLite) {
+      this.isRenderingVegaLite = false;
+      await emit?.({
+        type: "rendering",
+        phase: "end",
+        label: "Rendering...",
+      });
+    }
+
+    const streamableLength = this.bufferedTextDelta.includes(VEGA_LITE_FENCE_START)
+      ? this.bufferedTextDelta.length
+      : this.bufferedTextDelta.length - getPartialVegaLiteFenceStartLength(this.bufferedTextDelta);
+
+    if (!streamableLength) {
+      return;
+    }
+
+    await emit?.({
+      type: "text-delta",
+      delta: this.bufferedTextDelta.slice(0, streamableLength),
+    });
+    this.bufferedTextDelta = this.bufferedTextDelta.slice(streamableLength);
+  }
+
+  async flush(emit?: AgentEventEmitter) {
+    if (this.isRenderingVegaLite) {
+      await emit?.({
+        type: "rendering",
+        phase: "end",
+        label: "Rendering...",
+      });
+      this.isRenderingVegaLite = false;
+    }
+
+    if (this.bufferedTextDelta) {
+      await emit?.({
+        type: "text-delta",
+        delta: this.bufferedTextDelta,
+      });
+      this.bufferedTextDelta = "";
+    }
+  }
+}
+
+function hasUnclosedLatestVegaLiteBlock(text: string): boolean {
+  const latestBlockStart = text.lastIndexOf(VEGA_LITE_FENCE_START);
+
+  if (latestBlockStart === -1) {
+    return false;
+  }
+
+  const blockContentStart = latestBlockStart + VEGA_LITE_FENCE_START.length;
+  return text.indexOf(FENCE_END, blockContentStart) === -1;
+}
+
+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/agent/turn/turnTypes.ts

@@ -0,0 +1,92 @@
+import type { AdminUser, AudioAdapter } from "adminforth";
+import type { Messages } 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";
+
+export type BaseAgentTurnInput = {
+  prompt: string;
+  sessionId: string;
+  modeName?: string | null;
+  userTimeZone?: string;
+  currentPage?: CurrentPageContext;
+  chatSurface?: string;
+  adminPublicOrigin?: string;
+  abortSignal?: AbortSignal;
+  adminUser: AdminUser;
+};
+
+export type TextAgentTurnInput = BaseAgentTurnInput & {
+  emit: AgentEventEmitter;
+  failureLogMessage?: string;
+  abortLogMessage?: string;
+};
+
+export type SpeechAgentTurnInput = Omit<BaseAgentTurnInput, "prompt"> & {
+  emit: AgentEventEmitter;
+  audioAdapter: AudioAdapter;
+  audio: {
+    buffer: Buffer;
+    filename: string;
+    mimeType: string;
+  };
+  failureLogMessage?: string;
+  abortLogMessage?: string;
+};
+
+export type AgentTurnContext = {
+  adminUser: AdminUser;
+  userTimeZone: string;
+  sessionId: string;
+  turnId: string;
+  abortSignal?: AbortSignal;
+  currentPage?: CurrentPageContext;
+  chatSurface?: string;
+  adminPublicOrigin?: string;
+};
+
+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;
+};
+
+export type AgentTurnModels = {
+  model: AgentChatModel;
+  summaryModel: AgentChatModel;
+  modelMiddleware?: AgentMiddleware[];
+};
+
+export type AgentRuntimeRunInput = {
+  models: AgentTurnModels;
+  messages: Messages;
+  context: AgentTurnContext;
+  observability: AgentTurnObservability;
+};
+
+export type RunAndPersistAgentResponseInput = BaseAgentTurnInput & {
+  emit?: AgentEventEmitter;
+  failureLogMessage: string;
+  abortLogMessage: string;
+};
+
+export type RunAndPersistAgentResponseResult = {
+  text: string;
+  turnId: string;
+  aborted: boolean;
+  failed: boolean;
+};
+
+export type HandleTurnInput = TextAgentTurnInput;
+export type HandleSpeechTurnInput = SpeechAgentTurnInput;