@adminforth/agent 1.43.28 → 1.44.0

package/index.ts

@@ -1,4 +1,12 @@
-import type { AdminUser, AdminForthResource, IAdminForth, IHttpServer } from "adminforth";
+import type {
+  AdminUser,
+  AdminForthResource,
+  ChatSurfaceAdapter,
+  ChatSurfaceEventSink,
+  ChatSurfaceIncomingMessage,
+  IAdminForth,
+  IHttpServer,
+} from "adminforth";
 
 import { AdminForthPlugin, logger, Filters, Sorts } from "adminforth";
 
@@ -12,12 +20,14 @@ 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 { createAgentEventStream } from "./agentResponseEvents.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 { ToolCallEvent } from "./agent/toolCallEvents.js";
 import type { CurrentPageContext } from "./agent/tools/getUserLocation.js";
 import { sanitizeSpeechText } from "./sanitizeSpeechText.js";
 
+export type { AgentEvent, AgentEventEmitter } from "./agentEvents.js";
+
 type MulterFile = {
   buffer: Buffer;
   originalname: string;
@@ -37,18 +47,21 @@ type AgentTurnRunInput = {
   abortSignal?: AbortSignal;
   adminUser: AdminUser;
   sequenceDebugCollector: ReturnType<typeof createSequenceDebugCollector>;
-  emitReasoningDelta?: (delta: string) => void;
-  emitTextDelta?: (delta: string) => void;
-  emitToolCallEvent?: (event: ToolCallEvent) => void;
+  emit?: AgentEventEmitter;
 };
 
 type RunAndPersistAgentResponseInput =
   Omit<AgentTurnRunInput, "turnId" | "sequenceDebugCollector" | "previousUserMessages"> & {
-    emitErrorResponse?: (response: string) => void;
     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(),
@@ -91,6 +104,14 @@ function getErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function requireAdminUser(adminUser: AdminUser | undefined): AdminUser {
+  if (!adminUser) {
+    throw new Error("AdminForth Agent endpoint requires an authenticated admin user");
+  }
+
+  return adminUser;
+}
+
 export default class AdminForthAgentPlugin extends AdminForthPlugin {
   options: PluginOptions;
   agentSystemPromptPromise: Promise<string>;
@@ -98,7 +119,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
   private parseBody<T>(
     schema: z.ZodType<T>,
     body: unknown,
-    response: { setStatus: (code: number, message?: string) => void },
+    response: { setStatus: (code: number, message: string) => void },
   ): T | null {
     const parsed = schema.safeParse(body ?? {});
     if (!parsed.success) {
@@ -146,6 +167,33 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       }));
   }
 
+  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;
 
@@ -215,6 +263,9 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
   
   validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
     this.options.audioAdapter?.validate();
+    for (const chatSurfaceAdapter of this.options.chatSurfaceAdapters ?? []) {
+      chatSurfaceAdapter.validate();
+    }
     this.agentSystemPromptPromise = buildAgentSystemPrompt(
       adminforth,
       this.getInternalAgentResourceIds(),
@@ -258,7 +309,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     const systemPrompt = buildAgentTurnSystemPrompt({
       agentSystemPrompt: await this.agentSystemPromptPromise,
       adminUser: input.adminUser,
-      usernameField: this.adminforth.config.auth.usernameField,
+      usernameField: this.adminforth.config.auth!.usernameField,
       userLanguage,
     });
     const apiBasedTools = buildApiBasedTools(
@@ -279,7 +330,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       adminUser: input.adminUser,
       adminforth: this.adminforth,
       apiBasedTools,
-      customComponentsDir: this.adminforth.config.customization.customComponentsDir,
+  customComponentsDir: this.adminforth.config.customization.customComponentsDir ?? "custom",
       sessionId: input.sessionId,
       turnId: input.turnId,
       currentPage: input.currentPage,
@@ -287,7 +338,10 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       abortSignal: input.abortSignal,
       emitToolCallEvent: (event) => {
         input.sequenceDebugCollector.handleToolCallEvent(event);
-        input.emitToolCallEvent?.(event);
+        void input.emit?.({
+          type: "tool-call",
+          data: event,
+        });
       },
       sequenceDebugSink: input.sequenceDebugCollector,
     });
@@ -324,12 +378,18 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         .join("");
 
       if (reasoningDelta) {
-        input.emitReasoningDelta?.(reasoningDelta);
+        await input.emit?.({
+          type: "reasoning-delta",
+          delta: reasoningDelta,
+        });
       }
 
       if (textDelta) {
         fullResponse += textDelta;
-        input.emitTextDelta?.(textDelta);
+        await input.emit?.({
+          type: "text-delta",
+          delta: textDelta,
+        });
       }
     }
 
@@ -361,9 +421,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         abortSignal: input.abortSignal,
         adminUser: input.adminUser,
         sequenceDebugCollector,
-        emitToolCallEvent: input.emitToolCallEvent,
-        emitReasoningDelta: input.emitReasoningDelta,
-        emitTextDelta: input.emitTextDelta,
+        emit: input.emit,
       });
       fullResponse = agentResponse.text;
     } catch (error) {
@@ -374,7 +432,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         failed = true;
         fullResponse = getErrorMessage(error);
         logger.error(`${input.failureLogMessage}:\n${fullResponse}`);
-        input.emitErrorResponse?.(fullResponse);
       }
     }
 
@@ -397,11 +454,140 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     };
   }
 
+  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 async handleChatSurfaceMessage(
+    adapter: ChatSurfaceAdapter,
+    incoming: ChatSurfaceIncomingMessage,
+    sink: ChatSurfaceEventSink,
+  ) {
+    const adminUser = await adapter.resolveAdminUser({
+      adminforth: this.adminforth,
+      incoming,
+    });
+
+    if (!adminUser) {
+      await sink.emit({
+        type: "error",
+        message: "This chat account is not authorized to use AdminForth Agent.",
+      });
+      return;
+    }
+
+    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) {
+    for (const adapter of this.options.chatSurfaceAdapters ?? []) {
+      server.endpoint({
+        method: "POST",
+        noAuth: true,
+        path: `/agent/surface/${adapter.name}/webhook`,
+        handler: async (ctx) => {
+          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 }) => {
+        const currentAdminUser = requireAdminUser(adminUser);
+
         if (!this.options.placeholderMessages) {
           return {
             messages: [],
@@ -409,7 +595,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         }
 
         const messages = await this.options.placeholderMessages({
-          adminUser,
+          adminUser: currentAdminUser,
           headers,
         });
 
@@ -422,28 +608,26 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/response`,
       handler: async ({ body, adminUser, response, _raw_express_res, abortSignal }) => {
+        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(agentResponseBodySchema, body, response);
         if (!data) return;
-        const stream = createAgentEventStream(_raw_express_res, {vercelAiUiMessageStream: true, closeActiveBlockOnToolStart: true});
-        const messageId = randomUUID();
+        const emit = createSseEventEmitter(_raw_express_res, {
+          vercelAiUiMessageStream: true,
+          closeActiveBlockOnToolStart: true,
+        });
 
-        stream.start(messageId);
-        await this.runAndPersistAgentResponse({
+        await this.handleTurn({
           prompt: data.message,
           sessionId: data.sessionId,
           modeName: data.mode,
           userTimeZone: data.timeZone ?? 'UTC',
           currentPage: data.currentPage,
           abortSignal,
-          adminUser,
-          emitToolCallEvent: stream.toolCall,
-          emitReasoningDelta: stream.reasoningDelta,
-          emitTextDelta: stream.textDelta,
-          emitErrorResponse: stream.textDelta,
+          adminUser: currentAdminUser,
+          emit,
           failureLogMessage: "Agent response streaming failed",
           abortLogMessage: "Agent response streaming aborted by the client",
         });
-        stream.end();
         return null;
       }
     });
@@ -452,19 +636,20 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       path: `/agent/speech-response`,
       target: 'upload',
       handler: async ({ body, adminUser, response, _raw_express_req, _raw_express_res, abortSignal }) => {
+        const currentAdminUser = requireAdminUser(adminUser);
         const req = _raw_express_req as ExpressMulterRequest;
         const audioAdapter = this.options.audioAdapter;
         if (!audioAdapter) {
-          response.setStatus(400, undefined);
+          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, undefined);
+          response.setStatus(400, "Audio file is required");
           return { error: "Audio file is required" };
         }
-        const stream = createAgentEventStream(_raw_express_res);
+        const emit = createSseEventEmitter(_raw_express_res);
         
         let transcription;
 
@@ -479,28 +664,38 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         } catch (error) {
           if (abortSignal.aborted || isAbortError(error)) {
             logger.info("Agent speech transcription aborted by the client");
-            stream.end();
+            await emit({ type: "finish" });
             return null;
           }
 
           logger.error(`Agent speech transcription failed:\n${getErrorMessage(error)}`);
-          stream.error("Speech transcription failed. Check server logs for details.");
-          stream.end();
+          await emit({
+            type: "error",
+            error: "Speech transcription failed. Check server logs for details.",
+          });
+          await emit({ type: "finish" });
           return null;
         }
 
         if (abortSignal.aborted) {
-          stream.end();
+          await emit({ type: "finish" });
           return null;
         }
 
         const prompt = transcription.text;
         if (!prompt) {
-          stream.error("Speech transcription is empty");
-          stream.end();
+          await emit({
+            type: "error",
+            error: "Speech transcription is empty",
+          });
+          await emit({ type: "finish" });
           return null;
         }
-        stream.transcript(transcription.text, transcription.language);
+        await emit({
+          type: "transcript",
+          text: transcription.text,
+          language: transcription.language,
+        });
 
         const sessionId = data.sessionId as string;
         const currentPage = data.currentPage;
@@ -511,35 +706,43 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
           userTimeZone: data.timeZone ?? 'UTC',
           currentPage,
           abortSignal,
-          adminUser,
-          emitToolCallEvent: stream.toolCall,
+          adminUser: currentAdminUser,
+          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) {
-          stream.end();
+          await emit({ type: "finish" });
           return null;
         }
 
         if (agentResponse.failed) {
-          stream.error(agentResponse.text);
-          stream.end();
+          await emit({
+            type: "error",
+            error: agentResponse.text,
+          });
+          await emit({ type: "finish" });
           return null;
         }
 
         try {
-          stream.speechResponse(
-            {
+          await emit({
+            type: "speech-response",
+            transcript: {
               text: transcription.text,
               language: transcription.language,
             },
-            {
+            response: {
               text: agentResponse.text,
             },
             sessionId,
-            agentResponse.turnId,
-          );
+            turnId: agentResponse.turnId,
+          });
           const speech = await audioAdapter.synthesize({
             text: sanitizeSpeechText(agentResponse.text),
             stream: true,
@@ -548,7 +751,14 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             abortSignal,
           });
 
-          stream.audioStart(speech.mimeType, speech.format, 24000, 1, 16);
+          await emit({
+            type: "audio-start",
+            mimeType: speech.mimeType,
+            format: speech.format,
+            sampleRate: 24000,
+            channelCount: 1,
+            bitsPerSample: 16,
+          });
 
           const reader = speech.audioStream.getReader();
           const cancelAudioStream = () => {
@@ -574,24 +784,30 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                 break;
               }
 
-              stream.audioDelta(value);
+              await emit({
+                type: "audio-delta",
+                value,
+              });
             }
           } finally {
             abortSignal.removeEventListener("abort", cancelAudioStream);
             reader.releaseLock();
           }
 
-          stream.audioDone();
-          stream.end();
+          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}`);
-            stream.error(error);
+            await emit({
+              type: "error",
+              error: getErrorMessage(error),
+            });
           }
-          stream.end();
+          await emit({ type: "finish" });
           return null;
         }
       }
@@ -600,9 +816,10 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/get-sessions`,
       handler: async ({body, adminUser, response }) => {
+        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(getSessionsBodySchema, body, response);
         if (!data) return;
-        const userId = adminUser.pk;
+        const userId = currentAdminUser.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)]
@@ -620,12 +837,13 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/get-session-info`,
       handler: async ({body, adminUser, response }) => {
+        const currentAdminUser = requireAdminUser(adminUser);
         const parsedBody = sessionIdBodySchema.safeParse(body);
         if (!parsedBody.success) {
           response.setStatus(422, parsedBody.error.message);
           return;
         }
-        const userId = adminUser.pk;
+        const userId = currentAdminUser.pk;
         const sessionId = parsedBody.data.sessionId;
         const session = await this.adminforth.resource(this.options.sessionResource.resourceId).get(
           [Filters.EQ(this.options.sessionResource.idField, sessionId)]
@@ -647,7 +865,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             title: session[this.options.sessionResource.titleField],
             timestamp: session[this.options.sessionResource.createdAtField],
             messages: turns.flatMap(turn => {
-              const messages = [];
+              const messages: Array<{ text: string; role: 'user' | 'assistant' }> = [];
               if (turn.prompt) {
                 messages.push({
                   text: turn.prompt,
@@ -670,10 +888,11 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/create-session`,
       handler: async ({body, adminUser, response }) => {
+        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(createSessionBodySchema, body, response);
         if (!data) return;
         const triggerMessage = data.triggerMessage;
-        const userId = adminUser.pk;
+        const userId = currentAdminUser.pk;
         const title = triggerMessage?.slice(0, 40) || "New Session";
         const newSession = {
           [this.options.sessionResource.idField]: randomUUID(),
@@ -693,10 +912,11 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/delete-session`,
       handler: async ({body, adminUser, response }) => {
+        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(sessionIdBodySchema, body, response);
         if (!data) return;
         const sessionId = data.sessionId;
-        const userId = adminUser.pk;
+        const userId = currentAdminUser.pk;
         const session = await this.adminforth.resource(this.options.sessionResource.resourceId).get(
           [Filters.EQ(this.options.sessionResource.idField, sessionId)]
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/agent",
-  "version": "1.43.28",
+  "version": "1.44.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "@langchain/core": "^1.1.40",
     "@langchain/langgraph": "^1.2.8",
     "@langchain/langgraph-checkpoint": "^1.0.1",
-    "adminforth": "^2.53.5",
+    "adminforth": ">=2.54.0",
     "dayjs": "^1.11.20",
     "langchain": "^1.3.3",
     "multer": "^2.1.1",