@adminforth/agent 1.45.0 → 1.46.0

package/index.ts

@@ -1,138 +1,33 @@
 import type {
-  AdminUser,
   AdminForthResource,
-  ChatSurfaceAdapter,
-  ChatSurfaceEventSink,
-  ChatSurfaceIncomingMessage,
-  IAdminForthEndpointHandlerInput,
   IAdminForth,
   IHttpServer,
 } from "adminforth";
 
-import { AdminForthPlugin, logger, Filters, Sorts } from "adminforth";
+import { AdminForthPlugin } from "adminforth";
 
 import type { PluginOptions } from './types.js';
-import { randomUUID } from 'crypto';
-import { HumanMessage, SystemMessage } from "langchain";
 import { MemorySaver, type BaseCheckpointSaver } from "@langchain/langgraph";
 import { z } from "zod";
-import { createAgentChatModel, callAgent } from "./agent/simpleAgent.js";
 import { AdminForthCheckpointSaver } from "./agent/checkpointer.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 { createSseEventEmitter } from "./surfaces/web-sse/createSseEventEmitter.js";
-import { appendCustomSystemPrompt, buildAgentSystemPrompt, buildAgentTurnSystemPrompt, DEFAULT_AGENT_SYSTEM_PROMPT} from "./agent/systemPrompt.js";
-import type { CurrentPageContext } from "./agent/tools/getUserLocation.js";
-import { sanitizeSpeechText } from "./sanitizeSpeechText.js";
+import { appendCustomSystemPrompt, buildAgentSystemPrompt, DEFAULT_AGENT_SYSTEM_PROMPT} from "./agent/systemPrompt.js";
+import { setupCoreEndpoints } from "./endpoints/core.js";
+import { setupSessionEndpoints } from "./endpoints/sessions.js";
+import { setupChatSurfaceEndpoints } from "./endpoints/chatSurfaces.js";
+import type { AgentEndpointsContext } from "./endpoints/context.js";
+import { AgentSessionStore } from "./sessionStore.js";
+import { ChatSurfaceService } from "./chatSurfaceService.js";
+import { AgentTurnService } from "./agentTurnService.js";
 
 export type { AgentEvent, AgentEventEmitter } from "./agentEvents.js";
 
-type MulterFile = {
-  buffer: Buffer;
-  originalname: string;
-  mimetype: string;
-};
-
-type ExpressMulterRequest = { file?: MulterFile };
-
-type ChatSurfaceConnectAction = {
-  type: "url";
-  label: string;
-  url: string;
-};
-
-type ChatSurfaceAdapterWithConnectAction = ChatSurfaceAdapter & {
-  createConnectAction?(input: {
-    token: string;
-  }): ChatSurfaceConnectAction | Promise<ChatSurfaceConnectAction>;
-};
-
-type ChatSurfaceLinkTokenPayload = {
-  surface: string;
-  adminUserId: AdminUser["pk"];
-  expiresAt: number;
-};
-
-type AgentTurnRunInput = {
-  prompt: string;
-  sessionId: string;
-  turnId: string;
-  previousUserMessages: PreviousUserMessage[];
-  modeName?: string | null;
-  userTimeZone: string;
-  currentPage?: CurrentPageContext;
-  abortSignal?: AbortSignal;
-  adminUser: AdminUser;
-  sequenceDebugCollector: ReturnType<typeof createSequenceDebugCollector>;
-  emit?: AgentEventEmitter;
-};
-
-type RunAndPersistAgentResponseInput =
-  Omit<AgentTurnRunInput, "turnId" | "sequenceDebugCollector" | "previousUserMessages"> & {
-    failureLogMessage: string;
-    abortLogMessage: string;
-  };
-
-type HandleTurnInput = Omit<RunAndPersistAgentResponseInput, "failureLogMessage" | "abortLogMessage"> & {
-  emit: AgentEventEmitter;
-  failureLogMessage?: string;
-  abortLogMessage?: string;
-};
-
-const agentResponseBodySchema = z.object({
-  message: z.string(),
-  sessionId: z.string(),
-  mode: z.string().nullish(),
-  timeZone: z.string().optional(),
-  currentPage: z.custom<CurrentPageContext>().optional(),
-}).strict();
-
-const agentSpeechResponseBodySchema = agentResponseBodySchema.omit({message: true})
-
-const addSystemMessageBodySchema = z.object({
-  sessionId: z.string(),
-  systemMessage: z.string(),
-}).strict();
-
-const getSessionsBodySchema = z.object({
-  limit: z.number().optional(),
-}).strict();
-
-const sessionIdBodySchema = z.object({
-  sessionId: z.string(),
-}).strict();
-
-const createSessionBodySchema = z.object({
-  triggerMessage: z.string().optional(),
-}).strict();
-
-const VEGA_LITE_FENCE_START = "```vega-lite";
-const COMPLETE_VEGA_LITE_BLOCK_RE = /```vega-lite[\s\S]*?```/;
-const DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD = "externalUserId";
-const CHAT_SURFACE_LINK_TOKEN_TTL_MS = 60 * 1000;
-
-function isAbortError(error: unknown): boolean {
-  return (
-    error instanceof DOMException && error.name === "AbortError"
-  ) || (
-    typeof error === "object" &&
-    error !== null &&
-    "name" in error &&
-    (error.name === "AbortError" || error.name === "APIUserAbortError")
-  );
-}
-
-function getErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export default class AdminForthAgentPlugin extends AdminForthPlugin {
   options: PluginOptions;
   agentSystemPromptPromise: Promise<string>;
   private checkpointer: BaseCheckpointSaver | null = null;
-  private chatSurfaceLinkTokens = new Map<string, ChatSurfaceLinkTokenPayload>();
+  private sessionStore: AgentSessionStore;
+  private agentTurnService: AgentTurnService;
+  private chatSurfaceService: ChatSurfaceService;
   private chatSurfaceSettingsPageRegistered = false;
   private parseBody<T>(
     schema: z.ZodType<T>,
@@ -146,72 +41,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     }
     return parsed.data;
   }
-  private async createNewTurn(sessionId: string, prompt: string, response?: string) {
-    const turnId = randomUUID();
-    const turnRecord = {
-      [this.options.turnResource.idField]: turnId,
-      [this.options.turnResource.sessionIdField]: sessionId,
-      [this.options.turnResource.promptField]: prompt,
-      [this.options.turnResource.responseField]: response || "not_finished",
-    };
-    const newTurn = await this.adminforth.resource(this.options.turnResource.resourceId).create(turnRecord);
-    return newTurn.createdRecord[this.options.turnResource.idField];
-  }
-
-  private async getSessionTurns(sessionId: string) {
-    const turns = await this.adminforth.resource(this.options.turnResource.resourceId).list(
-      [Filters.EQ(this.options.turnResource.sessionIdField, sessionId)],
-      undefined,
-      undefined,
-      [Sorts.ASC(this.options.turnResource.createdAtField)]
-    );
-    return turns.map(turn => ({
-      prompt: turn[this.options.turnResource.promptField],
-      response: turn[this.options.turnResource.responseField],
-    }));
-  }
-
-  private async getPreviousUserMessages(sessionId: string) {
-    const turns = await this.adminforth.resource(this.options.turnResource.resourceId).list(
-      [Filters.EQ(this.options.turnResource.sessionIdField, sessionId)],
-      2,
-      undefined,
-      [Sorts.DESC(this.options.turnResource.createdAtField)]
-    );
-    return turns
-      .reverse()
-      .map((turn): PreviousUserMessage => ({
-        text: turn[this.options.turnResource.promptField],
-      }));
-  }
-
-  private getChatSurfaceSessionId(incoming: ChatSurfaceIncomingMessage) {
-    return `${incoming.surface}:${incoming.externalConversationId}`;
-  }
-
-  private async getOrCreateChatSurfaceSession(
-    incoming: ChatSurfaceIncomingMessage,
-    adminUser: AdminUser,
-  ) {
-    const sessionId = this.getChatSurfaceSessionId(incoming);
-    const sessionResource = this.adminforth.resource(this.options.sessionResource.resourceId);
-    const session = await sessionResource.get(
-      [Filters.EQ(this.options.sessionResource.idField, sessionId)]
-    );
-
-    if (session) {
-      return sessionId;
-    }
-
-    await sessionResource.create({
-      [this.options.sessionResource.idField]: sessionId,
-      [this.options.sessionResource.titleField]: incoming.prompt.slice(0, 40) || "New Session",
-      [this.options.sessionResource.askerIdField]: adminUser.pk,
-    });
-
-    return sessionId;
-  }
-
   private getCheckpointer() {
     if (this.checkpointer) return this.checkpointer;
 
@@ -230,15 +59,26 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     ].filter((resourceId): resourceId is string => Boolean(resourceId));
   }
 
-  private getChatSurfaceConnectActionAdapters() {
-    return (this.options.chatSurfaceAdapters ?? [])
-      .map((adapter) => adapter as ChatSurfaceAdapterWithConnectAction)
-      .filter((adapter) => adapter.createConnectAction);
-  }
-
   constructor(options: PluginOptions) {
     super(options, import.meta.url);
     this.options = options;
+    this.sessionStore = new AgentSessionStore(() => this.adminforth, this.options);
+    this.agentTurnService = new AgentTurnService({
+      getAdminforth: () => this.adminforth,
+      getPluginInstanceId: () => this.pluginInstanceId,
+      options: this.options,
+      sessionStore: this.sessionStore,
+      getCheckpointer: this.getCheckpointer.bind(this),
+      getInternalAgentResourceIds: this.getInternalAgentResourceIds.bind(this),
+      getAgentSystemPrompt: () => this.agentSystemPromptPromise,
+    });
+    this.chatSurfaceService = new ChatSurfaceService(
+      () => this.adminforth,
+      this.options,
+      this.sessionStore,
+      this.agentTurnService.handleTurn.bind(this.agentTurnService),
+      this.agentTurnService.runAndPersistAgentResponse.bind(this.agentTurnService),
+    );
     this.agentSystemPromptPromise = Promise.resolve(
       appendCustomSystemPrompt(DEFAULT_AGENT_SYSTEM_PROMPT, this.options.systemPrompt),
     );
@@ -263,7 +103,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         hasAudioAdapter: Boolean(this.options.audioAdapter),
       }
     });
-    if (this.getChatSurfaceConnectActionAdapters().length && !this.chatSurfaceSettingsPageRegistered) {
+    if (this.chatSurfaceService.getConnectActionAdapters().length && !this.chatSurfaceSettingsPageRegistered) {
       if (!this.adminforth.config.auth!.userMenuSettingsPages) {
         this.adminforth.config.auth!.userMenuSettingsPages = [];
       }
@@ -314,869 +154,24 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     return `single`;
   }
 
-  private async runAgentTurn(input: AgentTurnRunInput) {
-    let fullResponse = "";
-    let bufferedTextDelta = "";
-    let isRenderingVegaLite = false;
-    const maxTokens = this.options.maxTokens ?? 1000;
-    const selectedMode = this.options.modes.find((mode) => mode.name === input.modeName) ?? this.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.agentSystemPromptPromise,
-      adminUser: input.adminUser,
-      usernameField: this.adminforth.config.auth!.usernameField,
-      userLanguage,
-    });
-    const apiBasedTools = buildApiBasedTools(
-      this.adminforth,
-      this.getInternalAgentResourceIds(),
-    );
-
-    const stream = await callAgent({
-      name: `adminforth-agent-${this.pluginInstanceId}`,
-      model,
-      summaryModel,
-      modelMiddleware,
-      checkpointer: this.getCheckpointer(),
-      messages: [
-        new SystemMessage(systemPrompt),
-        new HumanMessage(input.prompt),
-      ],
-      adminUser: input.adminUser,
-      adminforth: this.adminforth,
-      apiBasedTools,
-  customComponentsDir: this.adminforth.config.customization.customComponentsDir ?? "custom",
-      sessionId: input.sessionId,
-      turnId: input.turnId,
-      currentPage: input.currentPage,
-      userTimeZone: input.userTimeZone,
-      abortSignal: input.abortSignal,
-      emitToolCallEvent: (event) => {
-        input.sequenceDebugCollector.handleToolCallEvent(event);
-        void input.emit?.({
-          type: "tool-call",
-          data: event,
-        });
-      },
-      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,
-    };
-  }
-
-  private async runAndPersistAgentResponse(input: RunAndPersistAgentResponseInput) {
-    const previousUserMessages = await this.getPreviousUserMessages(input.sessionId);
-    const turnId = await this.createNewTurn(input.sessionId, input.prompt);
-    await this.adminforth.resource(this.options.sessionResource.resourceId).update(input.sessionId, {
-      [this.options.sessionResource.createdAtField]: new Date().toISOString(),
-    });
-    const sequenceDebugCollector = createSequenceDebugCollector();
-    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,
-        abortSignal: input.abortSignal,
-        adminUser: input.adminUser,
-        sequenceDebugCollector,
-        emit: input.emit,
-      });
-      fullResponse = agentResponse.text;
-    } catch (error) {
-      if (input.abortSignal?.aborted || isAbortError(error)) {
-        aborted = true;
-        logger.info(input.abortLogMessage);
-      } else {
-        failed = true;
-        fullResponse = getErrorMessage(error);
-        logger.error(`${input.failureLogMessage}:\n${fullResponse}`);
-      }
-    }
-
-    sequenceDebugCollector.flush();
-    const turnUpdates: Record<string, unknown> = {
-      [this.options.turnResource.responseField]: fullResponse,
-    };
-
-    if (this.options.turnResource.debugField) {
-      turnUpdates[this.options.turnResource.debugField] = sequenceDebugCollector.getHistory();
-    }
-
-    await this.adminforth.resource(this.options.turnResource.resourceId).update(turnId, turnUpdates);
-
-    return {
-      text: fullResponse,
-      turnId,
-      aborted,
-      failed,
-    };
-  }
-
-  async handleTurn(input: HandleTurnInput) {
-    await input.emit({
-      type: "turn-started",
-      messageId: randomUUID(),
-    });
-
-    const agentResponse = await this.runAndPersistAgentResponse({
-      prompt: input.prompt,
-      sessionId: input.sessionId,
-      modeName: input.modeName,
-      userTimeZone: input.userTimeZone,
-      currentPage: input.currentPage,
-      abortSignal: input.abortSignal,
-      adminUser: input.adminUser,
-      emit: input.emit,
-      failureLogMessage: input.failureLogMessage ?? "Agent response failed",
-      abortLogMessage: input.abortLogMessage ?? "Agent response aborted",
-    });
-
-    if (agentResponse.failed) {
-      await input.emit({
-        type: "error",
-        error: agentResponse.text,
-      });
-    } else if (!agentResponse.aborted) {
-      await input.emit({
-        type: "response",
-        text: agentResponse.text,
-        sessionId: input.sessionId,
-        turnId: agentResponse.turnId,
-      });
-    }
-
-    await input.emit({
-      type: "finish",
-    });
-
-    return agentResponse;
-  }
-
-  private createChatSurfaceEventEmitter(sink: ChatSurfaceEventSink): AgentEventEmitter {
-    return async (event) => {
-      if (event.type === "text-delta") {
-        await sink.emit({
-          type: "text_delta",
-          delta: event.delta,
-        });
-        return;
-      }
-
-      if (event.type === "response") {
-        await sink.emit({
-          type: "done",
-          text: event.text,
-        });
-        return;
-      }
-
-      if (event.type === "error") {
-        await sink.emit({
-          type: "error",
-          message: event.error,
-        });
-      }
-    };
-  }
-
-  private createChatSurfaceLinkToken(surface: string, adminUser: AdminUser) {
-    for (const [token, payload] of this.chatSurfaceLinkTokens) {
-      if (payload.expiresAt <= Date.now()) {
-        this.chatSurfaceLinkTokens.delete(token);
-      }
-    }
-
-    const token = randomUUID();
-    this.chatSurfaceLinkTokens.set(token, {
-      surface,
-      adminUserId: adminUser.pk,
-      expiresAt: Date.now() + CHAT_SURFACE_LINK_TOKEN_TTL_MS,
-    });
-
-    return token;
-  }
-
-  private consumeChatSurfaceLinkToken(surface: string, token: string) {
-    const payload = this.chatSurfaceLinkTokens.get(token);
-    this.chatSurfaceLinkTokens.delete(token);
-
-    if (!payload || payload.surface !== surface || payload.expiresAt <= Date.now()) {
-      return null;
-    }
-
-    return payload;
-  }
-
-  private async handleChatSurfaceLink(
-    incoming: ChatSurfaceIncomingMessage,
-    sink: ChatSurfaceEventSink,
-  ) {
-    if (typeof incoming.metadata?.startPayload !== "string") {
-      return false;
-    }
-
-    const payload = this.consumeChatSurfaceLinkToken(incoming.surface, incoming.metadata.startPayload);
-    if (!payload) {
-      await sink.emit({
-        type: "error",
-        message: "This chat surface link is expired or invalid. Please start linking again from AdminForth.",
-      });
-      return true;
-    }
-    const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
-    const authResourceId = this.adminforth.config.auth!.usersResourceId!;
-    const authResource = this.adminforth.config.resources.find((resource) => resource.resourceId === authResourceId)!;
-    const primaryKeyField = authResource.columns.find((column) => column.primaryKey)!.name!;
-    const adminUserRecord = await this.adminforth.resource(authResourceId).get([
-      Filters.EQ(primaryKeyField, payload.adminUserId),
-    ]);
-
-    await this.adminforth.resource(authResourceId).update(payload.adminUserId, {
-      [externalUserIdField]: {
-        ...(adminUserRecord[externalUserIdField] ?? {}),
-        [incoming.surface]: incoming.externalUserId,
-      },
-    });
-    await sink.emit({
-      type: "done",
-      text: `${incoming.surface} account connected to AdminForth.`,
-    });
-
-    return true;
-  }
-
-  private async handleChatSurfaceMessage(
-    adapter: ChatSurfaceAdapter,
-    incoming: ChatSurfaceIncomingMessage,
-    sink: ChatSurfaceEventSink,
-  ) {
-    if (await this.handleChatSurfaceLink(incoming, sink)) {
-      return;
-    }
-
-    const authResourceId = this.adminforth.config.auth!.usersResourceId!;
-    const authResource = this.adminforth.config.resources.find((resource) => resource.resourceId === authResourceId)!;
-    const primaryKeyField = authResource.columns.find((column) => column.primaryKey)!.name!;
-    const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
-    const adminUserRecord = (
-      await this.adminforth.resource(authResourceId).list(Filters.IS_NOT_EMPTY(externalUserIdField))
-    ).find((user) => user[externalUserIdField]?.[adapter.name] === incoming.externalUserId);
-
-    if (!adminUserRecord) {
-      await sink.emit({
-        type: "error",
-        message: "This chat account is not authorized to use AdminForth Agent.",
-      });
-      return;
-    }
-
-    const adminUser = {
-      pk: adminUserRecord[primaryKeyField],
-      username: adminUserRecord[this.adminforth.config.auth!.usernameField],
-      dbUser: adminUserRecord,
-    };
-
-    await this.handleTurn({
-      prompt: incoming.prompt,
-      sessionId: await this.getOrCreateChatSurfaceSession(incoming, adminUser),
-      modeName: incoming.modeName,
-      userTimeZone: incoming.userTimeZone ?? "UTC",
-      adminUser,
-      emit: this.createChatSurfaceEventEmitter(sink),
-      failureLogMessage: `Agent ${incoming.surface} surface response failed`,
-      abortLogMessage: `Agent ${incoming.surface} surface response aborted`,
-    });
-  }
-
   setupEndpoints(server: IHttpServer) {
-    if (this.getChatSurfaceConnectActionAdapters().length) {
-      server.endpoint({
-        method: "POST",
-        path: "/agent/surfaces/connectable",
-        handler: async ({ adminUser }) => {
-          const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
-          const externalIds = adminUser.dbUser[externalUserIdField] ?? {};
-
-          return {
-            surfaces: this.getChatSurfaceConnectActionAdapters().map((adapter) => ({
-              name: adapter.name,
-              externalUserId: externalIds[adapter.name] ?? null,
-            })),
-          };
-        },
-      });
-    }
-
-    for (const adapter of this.options.chatSurfaceAdapters ?? []) {
-      const connectActionAdapter = adapter as ChatSurfaceAdapterWithConnectAction;
-      if (connectActionAdapter.createConnectAction) {
-        server.endpoint({
-          method: "POST",
-          path: `/agent/surface/${adapter.name}/connect-action`,
-          handler: async ({ adminUser }) => {
-            const token = this.createChatSurfaceLinkToken(adapter.name, adminUser);
-            const action = await connectActionAdapter.createConnectAction!({ token });
-
-            return {
-              action,
-            };
-          },
-        });
-        server.endpoint({
-          method: "POST",
-          path: `/agent/surface/${adapter.name}/disconnect`,
-          handler: async ({ adminUser }) => {
-            const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
-            const externalIds = {
-              ...(adminUser.dbUser[externalUserIdField] ?? {}),
-            };
-
-            delete externalIds[adapter.name];
-
-            await this.adminforth.resource(this.adminforth.config.auth!.usersResourceId!).update(adminUser.pk, {
-              [externalUserIdField]: externalIds,
-            });
-
-            return {
-              ok: true,
-            };
-          },
-        });
-      }
-
-      server.endpoint({
-        method: "POST",
-        noAuth: true,
-        path: `/agent/surface/${adapter.name}/webhook`,
-        handler: async (ctx: IAdminForthEndpointHandlerInput) => {
-          const surfaceContext = {
-            body: ctx.body,
-            headers: ctx.headers,
-            abortSignal: ctx.abortSignal,
-            rawRequest: ctx._raw_express_req,
-            rawResponse: ctx._raw_express_res,
-          };
-          const incoming = await adapter.parseIncomingMessage(surfaceContext);
-
-          if (!incoming) return { ok: true };
-
-          const sink = await adapter.createEventSink(surfaceContext, incoming);
-
-          try {
-            await this.handleChatSurfaceMessage(adapter, incoming, sink);
-          } finally {
-            await sink.close?.();
-          }
-
-          return { ok: true };
-        },
-      });
-    }
-
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/get-placeholder-messages`,
-      handler: async ({ headers, adminUser }) => {
-        if (!this.options.placeholderMessages) {
-          return {
-            messages: [],
-          };
-        }
-
-        const messages = await this.options.placeholderMessages({
-          adminUser: adminUser,
-          headers,
-        });
-
-        return {
-          messages,
-        };
-      }
-    });
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/response`,
-      handler: async ({ body, adminUser, response, _raw_express_res, abortSignal }) => {
-        const data = this.parseBody(agentResponseBodySchema, body, response);
-        if (!data) return;
-        const emit = createSseEventEmitter(_raw_express_res, {
-          vercelAiUiMessageStream: true,
-          closeActiveBlockOnToolStart: true,
-        });
-
-        await this.handleTurn({
-          prompt: data.message,
-          sessionId: data.sessionId,
-          modeName: data.mode,
-          userTimeZone: data.timeZone ?? 'UTC',
-          currentPage: data.currentPage,
-          abortSignal,
-          adminUser: adminUser,
-          emit,
-          failureLogMessage: "Agent response streaming failed",
-          abortLogMessage: "Agent response streaming aborted by the client",
-        });
-        return null;
-      }
-    });
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/speech-response`,
-      target: 'upload',
-      handler: async ({ body, adminUser, response, _raw_express_req, _raw_express_res, abortSignal }) => {
-        const req = _raw_express_req as ExpressMulterRequest;
-        const audioAdapter = this.options.audioAdapter;
-        if (!audioAdapter) {
-          response.setStatus(400, "Audio adapter is not configured for AdminForth Agent");
-          return { error: "Audio adapter is not configured for AdminForth Agent" };
-        }
-        const data = this.parseBody(agentSpeechResponseBodySchema, body, response);
-        if (!data) return;
-        if (!req.file) {
-          response.setStatus(400, "Audio file is required");
-          return { error: "Audio file is required" };
-        }
-        const emit = createSseEventEmitter(_raw_express_res);
-        
-        let transcription;
-
-        try {
-          transcription = await audioAdapter.transcribe({
-            buffer: req.file.buffer,
-            filename: req.file.originalname,
-            mimeType: req.file.mimetype,
-            language: "auto",
-            abortSignal,
-          });
-        } catch (error) {
-          if (abortSignal.aborted || isAbortError(error)) {
-            logger.info("Agent speech transcription aborted by the client");
-            await emit({ type: "finish" });
-            return null;
-          }
-
-          logger.error(`Agent speech transcription failed:\n${getErrorMessage(error)}`);
-          await emit({
-            type: "error",
-            error: "Speech transcription failed. Check server logs for details.",
-          });
-          await emit({ type: "finish" });
-          return null;
-        }
-
-        if (abortSignal.aborted) {
-          await emit({ type: "finish" });
-          return null;
-        }
-
-        const prompt = transcription.text;
-        if (!prompt) {
-          await emit({
-            type: "error",
-            error: "Speech transcription is empty",
-          });
-          await emit({ type: "finish" });
-          return null;
-        }
-        await emit({
-          type: "transcript",
-          text: transcription.text,
-          language: transcription.language,
-        });
-
-        const sessionId = data.sessionId as string;
-        const currentPage = data.currentPage;
-        const agentResponse = await this.runAndPersistAgentResponse({
-          prompt,
-          sessionId,
-          modeName: data.mode,
-          userTimeZone: data.timeZone ?? 'UTC',
-          currentPage,
-          abortSignal,
-          adminUser: adminUser,
-          emit: async (event) => {
-            if (event.type === "tool-call") {
-              await emit(event);
-            }
-          },
-          failureLogMessage: "Agent speech response failed",
-          abortLogMessage: "Agent speech response aborted by the client",
-        });
-
-        if (agentResponse.aborted) {
-          await emit({ type: "finish" });
-          return null;
-        }
-
-        if (agentResponse.failed) {
-          await emit({
-            type: "error",
-            error: agentResponse.text,
-          });
-          await emit({ type: "finish" });
-          return null;
-        }
-
-        try {
-          await emit({
-            type: "speech-response",
-            transcript: {
-              text: transcription.text,
-              language: transcription.language,
-            },
-            response: {
-              text: agentResponse.text,
-            },
-            sessionId,
-            turnId: agentResponse.turnId,
-          });
-          const speech = await audioAdapter.synthesize({
-            text: sanitizeSpeechText(agentResponse.text),
-            stream: true,
-            streamFormat: "audio",
-            format: "pcm",
-            abortSignal,
-          });
-
-          await 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 {
-            abortSignal.addEventListener("abort", cancelAudioStream, { once: true });
-
-            while (true) {
-              if (abortSignal.aborted) {
-                await reader.cancel().catch(() => undefined);
-                break;
-              }
-
-              const { value, done } = await reader.read();
-
-              if (done) {
-                break;
-              }
-
-              if (abortSignal.aborted) {
-                break;
-              }
-
-              await emit({
-                type: "audio-delta",
-                value,
-              });
-            }
-          } finally {
-            abortSignal.removeEventListener("abort", cancelAudioStream);
-            reader.releaseLock();
-          }
-
-          await emit({ type: "audio-done" });
-          await emit({ type: "finish" });
-          return null;
-        } catch (error) {
-          if (abortSignal.aborted || isAbortError(error)) {
-            logger.info("Agent speech audio streaming aborted by the client");
-          } else {
-            logger.error(`Agent speech audio streaming failed:\n${error}`);
-            await emit({
-              type: "error",
-              error: getErrorMessage(error),
-            });
-          }
-          await emit({ type: "finish" });
-          return null;
-        }
-      }
-    });
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/get-sessions`,
-      handler: async ({body, adminUser, response }) => {
-        const data = this.parseBody(getSessionsBodySchema, body, response);
-        if (!data) return;
-        const userId = adminUser.pk;
-        const limit = data.limit ?? 20;
-        const sessions = await this.adminforth.resource(this.options.sessionResource.resourceId).list(
-          [Filters.EQ(this.options.sessionResource.askerIdField, userId)], limit, undefined, [Sorts.DESC(this.options.sessionResource.createdAtField)]
-        );
-        return {
-          sessions: sessions.map((session) => ({
-            sessionId: session[this.options.sessionResource.idField],
-            title: session[this.options.sessionResource.titleField],
-            timestamp: session[this.options.sessionResource.createdAtField],
-          })),
-        };
-      }
-    });
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/get-session-info`,
-      handler: async ({body, adminUser, response }) => {
-        const parsedBody = sessionIdBodySchema.safeParse(body);
-        if (!parsedBody.success) {
-          response.setStatus(422, parsedBody.error.message);
-          return;
-        }
-        const userId = adminUser.pk;
-        const sessionId = parsedBody.data.sessionId;
-        const session = await this.adminforth.resource(this.options.sessionResource.resourceId).get(
-          [Filters.EQ(this.options.sessionResource.idField, sessionId)]
-        );
-        if (!session) {
-          return {
-            error: 'Session not found'
-          };
-        }
-        if (session[this.options.sessionResource.askerIdField] !== userId) {
-          return {
-            error: 'Unauthorized'
-          };
-        }
-        const turns = await this.getSessionTurns(sessionId);
-        return {
-          session: {
-            sessionId,
-            title: session[this.options.sessionResource.titleField],
-            timestamp: session[this.options.sessionResource.createdAtField],
-            messages: turns.flatMap(turn => {
-              const messages: Array<{ text: string; role: 'user' | 'assistant' }> = [];
-              if (turn.prompt) {
-                messages.push({
-                  text: turn.prompt,
-                  role: 'user',
-                });
-              }
-              if (turn.response && turn.response !== "not_finished") {
-                messages.push({
-                  text: turn.response,
-                  role: 'assistant',
-                });
-              }
-              return messages;
-            }),
-          },
-        };
-      }
-    });
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/create-session`,
-      handler: async ({body, adminUser, response }) => {
-        const data = this.parseBody(createSessionBodySchema, body, response);
-        if (!data) return;
-        const triggerMessage = data.triggerMessage;
-        const userId = adminUser.pk;
-        const title = triggerMessage?.slice(0, 40) || "New Session";
-        const newSession = {
-          [this.options.sessionResource.idField]: randomUUID(),
-          [this.options.sessionResource.titleField]: title,
-          [this.options.sessionResource.askerIdField]: userId,
-        };
-        await this.adminforth.resource(this.options.sessionResource.resourceId).create(newSession);
-        return {
-          sessionId: newSession[this.options.sessionResource.idField],
-          title: newSession[this.options.sessionResource.titleField],
-          timestamp: newSession[this.options.sessionResource.createdAtField],
-          messages: []
-        };
-      }
-    });
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/delete-session`,
-      handler: async ({body, adminUser, response }) => {
-        const data = this.parseBody(sessionIdBodySchema, body, response);
-        if (!data) return;
-        const sessionId = data.sessionId;
-        const userId = adminUser.pk;
-        const session = await this.adminforth.resource(this.options.sessionResource.resourceId).get(
-          [Filters.EQ(this.options.sessionResource.idField, sessionId)]
-        );
-        if (!session) {
-          return {
-            error: 'Session not found'
-          };
-        }
-        if (session[this.options.sessionResource.askerIdField] !== userId) {
-          return {
-            error: 'Unauthorized'
-          };
-        }
-        await this.adminforth.resource(this.options.sessionResource.resourceId).delete(sessionId);
-        const turns = await this.adminforth.resource(this.options.turnResource.resourceId).list(
-          [Filters.EQ(this.options.turnResource.sessionIdField, sessionId)]
-        );
-        for (const turn of turns) {
-          await this.adminforth.resource(this.options.turnResource.resourceId).delete(turn[this.options.turnResource.idField]);
-        }
-        return {
-          ok: true
-        };
-      }
-    }),
-    server.endpoint({
-      method: 'POST',
-      path: `/agent/add-system-message-to-turns`,
-      handler: async ({body, response }) => {
-        const data = this.parseBody(addSystemMessageBodySchema, body, response);
-        if (!data) return;
-        await this.createNewTurn(data.sessionId, data.systemMessage);
-        return {
-          ok: true
-        }
-      }
-    })
-  }
-}
-
-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;
-    }
+    const endpointContext = {
+      adminforth: this.adminforth,
+      options: this.options,
+      parseBody: this.parseBody.bind(this),
+      handleTurn: this.agentTurnService.handleTurn.bind(this.agentTurnService),
+      handleSpeechTurn: this.agentTurnService.handleSpeechTurn.bind(this.agentTurnService),
+      runAndPersistAgentResponse: this.agentTurnService.runAndPersistAgentResponse.bind(this.agentTurnService),
+      getSessionTurns: this.sessionStore.getSessionTurns.bind(this.sessionStore),
+      createNewTurn: this.sessionStore.createNewTurn.bind(this.sessionStore),
+      createSystemTurn: this.sessionStore.createSystemTurn.bind(this.sessionStore),
+      getChatSurfaceConnectActionAdapters: this.chatSurfaceService.getConnectActionAdapters.bind(this.chatSurfaceService),
+      createChatSurfaceLinkToken: this.chatSurfaceService.createLinkToken.bind(this.chatSurfaceService),
+      handleChatSurfaceMessage: this.chatSurfaceService.handleMessage.bind(this.chatSurfaceService),
+    } satisfies AgentEndpointsContext;
+
+    setupCoreEndpoints(endpointContext, server);
+    setupSessionEndpoints(endpointContext, server);
+    setupChatSurfaceEndpoints(endpointContext, server);
   }
-
-  return 0;
 }