@adminforth/agent 1.44.2 → 1.45.1

package/dist/sessionStore.d.ts

@@ -0,0 +1,19 @@
+import type { AdminUser, IAdminForth } from "adminforth";
+import type { ChatSurfaceIncomingMessage } from "adminforth";
+import type { PreviousUserMessage } from "./agent/languageDetect.js";
+import type { PluginOptions } from "./types.js";
+export declare const AGENT_SYSTEM_TURN_PROMPT = "__adminforth_system_message__";
+export declare class AgentSessionStore {
+    private getAdminforth;
+    private options;
+    constructor(getAdminforth: () => IAdminForth, options: PluginOptions);
+    createNewTurn(sessionId: string, prompt: string, response?: string): Promise<any>;
+    createSystemTurn(sessionId: string, systemMessage: string): Promise<any>;
+    getSessionTurns(sessionId: string): Promise<{
+        prompt: any;
+        response: any;
+    }[]>;
+    getPreviousUserMessages(sessionId: string): Promise<PreviousUserMessage[]>;
+    getChatSurfaceSessionId(incoming: ChatSurfaceIncomingMessage): string;
+    getOrCreateChatSurfaceSession(incoming: ChatSurfaceIncomingMessage, adminUser: AdminUser): Promise<string>;
+}

package/dist/sessionStore.js

@@ -0,0 +1,83 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Filters, Sorts } from "adminforth";
+import { randomUUID } from "crypto";
+export const AGENT_SYSTEM_TURN_PROMPT = "__adminforth_system_message__";
+export class AgentSessionStore {
+    constructor(getAdminforth, options) {
+        this.getAdminforth = getAdminforth;
+        this.options = options;
+    }
+    createNewTurn(sessionId, prompt, response) {
+        return __awaiter(this, void 0, void 0, function* () {
+            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 !== null && response !== void 0 ? response : "not_finished",
+            };
+            const newTurn = yield this.getAdminforth().resource(this.options.turnResource.resourceId).create(turnRecord);
+            return newTurn.createdRecord[this.options.turnResource.idField];
+        });
+    }
+    createSystemTurn(sessionId, systemMessage) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const turnId = randomUUID();
+            const turnRecord = {
+                [this.options.turnResource.idField]: turnId,
+                [this.options.turnResource.sessionIdField]: sessionId,
+                [this.options.turnResource.promptField]: AGENT_SYSTEM_TURN_PROMPT,
+                [this.options.turnResource.responseField]: systemMessage,
+            };
+            const newTurn = yield this.getAdminforth().resource(this.options.turnResource.resourceId).create(turnRecord);
+            return newTurn.createdRecord[this.options.turnResource.idField];
+        });
+    }
+    getSessionTurns(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const turns = yield this.getAdminforth().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],
+            }));
+        });
+    }
+    getPreviousUserMessages(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const turns = yield this.getAdminforth().resource(this.options.turnResource.resourceId).list([Filters.EQ(this.options.turnResource.sessionIdField, sessionId)], 2, undefined, [Sorts.DESC(this.options.turnResource.createdAtField)]);
+            return turns
+                .reverse()
+                .filter((turn) => turn[this.options.turnResource.promptField] !== AGENT_SYSTEM_TURN_PROMPT)
+                .map((turn) => ({
+                text: turn[this.options.turnResource.promptField],
+            }));
+        });
+    }
+    getChatSurfaceSessionId(incoming) {
+        return `${incoming.surface}:${incoming.externalConversationId}`;
+    }
+    getOrCreateChatSurfaceSession(incoming, adminUser) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sessionId = this.getChatSurfaceSessionId(incoming);
+            const sessionResource = this.getAdminforth().resource(this.options.sessionResource.resourceId);
+            const session = yield sessionResource.get([Filters.EQ(this.options.sessionResource.idField, sessionId)]);
+            if (session) {
+                return sessionId;
+            }
+            yield 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;
+        });
+    }
+}

package/dist/types.d.ts

@@ -90,5 +90,9 @@ export interface PluginOptions extends PluginsCommonOptions {
      * Falls back to an in-memory MemorySaver when omitted.
      */
     checkpointResource?: ICheckpointResource;
+    /**
+     * Optional field for storing external chat IDs.
+     */
+    chatExternalIdsField?: string;
 }
 export {};

package/endpoints/chatSurfaces.ts

@@ -0,0 +1,93 @@
+import type {
+  IAdminForthEndpointHandlerInput,
+  IHttpServer,
+} from "adminforth";
+import type { ChatSurfaceAdapterWithConnectAction, ChatSurfaceEndpointsContext } from "./context.js";
+
+const DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD = "externalUserId";
+
+export function setupChatSurfaceEndpoints(ctx: ChatSurfaceEndpointsContext, server: IHttpServer) {
+  if (ctx.getChatSurfaceConnectActionAdapters().length) {
+    server.endpoint({
+      method: "POST",
+      path: "/agent/surfaces/connectable",
+      handler: async ({ adminUser }) => {
+        const externalUserIdField = ctx.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+        const externalIds = adminUser!.dbUser[externalUserIdField] ?? {};
+
+        return {
+          surfaces: ctx.getChatSurfaceConnectActionAdapters().map((adapter) => ({
+            name: adapter.name,
+            externalUserId: externalIds[adapter.name] ?? null,
+          })),
+        };
+      },
+    });
+  }
+
+  for (const adapter of ctx.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 = ctx.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 = ctx.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+          const externalIds = {
+            ...(adminUser!.dbUser[externalUserIdField] ?? {}),
+          };
+
+          delete externalIds[adapter.name];
+
+          await ctx.adminforth.resource(ctx.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 (endpointInput: IAdminForthEndpointHandlerInput) => {
+        const surfaceContext = {
+          body: endpointInput.body,
+          headers: endpointInput.headers,
+          abortSignal: endpointInput.abortSignal,
+          rawRequest: endpointInput._raw_express_req,
+          rawResponse: endpointInput._raw_express_res,
+        };
+        const incoming = await adapter.parseIncomingMessage(surfaceContext);
+
+        if (!incoming) return { ok: true };
+
+        const sink = await adapter.createEventSink(surfaceContext, incoming);
+
+        try {
+          await ctx.handleChatSurfaceMessage(adapter, incoming, sink);
+        } finally {
+          await sink.close?.();
+        }
+
+        return { ok: true };
+      },
+    });
+  }
+}

package/endpoints/context.ts

@@ -0,0 +1,66 @@
+import type {
+  AdminUser,
+  ChatSurfaceAdapter,
+  ChatSurfaceEventSink,
+  ChatSurfaceIncomingMessage,
+  IAdminForth,
+} from "adminforth";
+import type { ZodType } from "zod";
+import type {
+  HandleSpeechTurnInput,
+  HandleTurnInput,
+  RunAndPersistAgentResponseInput,
+  RunAndPersistAgentResponseResult,
+} from "../agentTurnService.js";
+import type { ChatSurfaceAdapterWithConnectAction } from "../chatSurfaceService.js";
+import type { PluginOptions } from "../types.js";
+
+export type { ChatSurfaceAdapterWithConnectAction } from "../chatSurfaceService.js";
+
+export type EndpointResponse = {
+  setStatus: (code: number, message: string) => void;
+};
+
+export type SessionTurn = {
+  prompt: string;
+  response: string;
+};
+
+export type AgentEndpointsContext = {
+  adminforth: IAdminForth;
+  options: PluginOptions;
+  parseBody<T>(schema: ZodType<T>, body: unknown, response: EndpointResponse): T | null;
+  handleTurn(input: HandleTurnInput): Promise<RunAndPersistAgentResponseResult>;
+  handleSpeechTurn(input: HandleSpeechTurnInput): Promise<RunAndPersistAgentResponseResult | null>;
+  runAndPersistAgentResponse(input: RunAndPersistAgentResponseInput): Promise<RunAndPersistAgentResponseResult>;
+  getSessionTurns(sessionId: string): Promise<SessionTurn[]>;
+  createNewTurn(sessionId: string, prompt: string, response?: string): Promise<string>;
+  createSystemTurn(sessionId: string, systemMessage: string): Promise<string>;
+  getChatSurfaceConnectActionAdapters(): ChatSurfaceAdapterWithConnectAction[];
+  createChatSurfaceLinkToken(surface: string, adminUser: AdminUser): string;
+  handleChatSurfaceMessage(
+    adapter: ChatSurfaceAdapter,
+    incoming: ChatSurfaceIncomingMessage,
+    sink: ChatSurfaceEventSink,
+  ): Promise<void>;
+};
+
+export type CoreEndpointsContext = Pick<
+  AgentEndpointsContext,
+  "options" | "parseBody" | "handleTurn" | "handleSpeechTurn"
+>;
+
+export type SessionEndpointsContext = Pick<
+  AgentEndpointsContext,
+  "adminforth" | "options" | "parseBody" | "getSessionTurns" | "createNewTurn"
+  | "createSystemTurn"
+>;
+
+export type ChatSurfaceEndpointsContext = Pick<
+  AgentEndpointsContext,
+  | "adminforth"
+  | "options"
+  | "getChatSurfaceConnectActionAdapters"
+  | "createChatSurfaceLinkToken"
+  | "handleChatSurfaceMessage"
+>;

package/endpoints/core.ts

@@ -0,0 +1,113 @@
+import type { IHttpServer } from "adminforth";
+import { z } from "zod";
+import { createSseEventEmitter } from "../surfaces/web-sse/createSseEventEmitter.js";
+import type { CurrentPageContext } from "../agent/tools/getUserLocation.js";
+import type { CoreEndpointsContext } from "./context.js";
+
+type MulterFile = {
+  buffer: Buffer;
+  originalname: string;
+  mimetype: string;
+};
+
+type ExpressMulterRequest = { file?: MulterFile };
+
+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 });
+
+export function setupCoreEndpoints(ctx: CoreEndpointsContext, server: IHttpServer) {
+  server.endpoint({
+    method: 'POST',
+    path: `/agent/get-placeholder-messages`,
+    handler: async ({ headers, adminUser }) => {
+      if (!ctx.options.placeholderMessages) {
+        return {
+          messages: [],
+        };
+      }
+
+      const messages = await ctx.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 = ctx.parseBody(agentResponseBodySchema, body, response);
+      if (!data) return;
+      const emit = createSseEventEmitter(_raw_express_res, {
+        vercelAiUiMessageStream: true,
+        closeActiveBlockOnToolStart: true,
+      });
+
+      await ctx.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 = ctx.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 = ctx.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);
+
+      await ctx.handleSpeechTurn({
+        audioAdapter,
+        audio: {
+          buffer: req.file.buffer,
+          filename: req.file.originalname,
+          mimeType: req.file.mimetype,
+        },
+        sessionId: data.sessionId,
+        modeName: data.mode,
+        userTimeZone: data.timeZone ?? 'UTC',
+        currentPage: data.currentPage,
+        abortSignal,
+        adminUser: adminUser!,
+        emit,
+        failureLogMessage: "Agent speech response failed",
+        abortLogMessage: "Agent speech response aborted by the client",
+      });
+      return null;
+    }
+  });
+}

package/endpoints/sessions.ts

@@ -0,0 +1,183 @@
+import type { IHttpServer } from "adminforth";
+import { Filters, Sorts } from "adminforth";
+import { randomUUID } from "crypto";
+import { z } from "zod";
+import { AGENT_SYSTEM_TURN_PROMPT } from "../sessionStore.js";
+import type { SessionEndpointsContext } from "./context.js";
+
+const addSystemMessageBodySchema = z.object({
+  sessionId: z.string(),
+  systemMessage: z.string(),
+}).strict();
+
+const getSessionsBodySchema = z.object({
+  limit: z.number().int().min(1).max(100).optional(),
+}).strict();
+
+const sessionIdBodySchema = z.object({
+  sessionId: z.string(),
+}).strict();
+
+const createSessionBodySchema = z.object({
+  triggerMessage: z.string().optional(),
+}).strict();
+
+export function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHttpServer) {
+  server.endpoint({
+    method: 'POST',
+    path: `/agent/get-sessions`,
+    handler: async ({body, adminUser, response }) => {
+      const data = ctx.parseBody(getSessionsBodySchema, body, response);
+      if (!data) return;
+      const userId = adminUser!.pk;
+      const limit = data.limit ?? 20;
+      const sessions = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).list(
+        [Filters.EQ(ctx.options.sessionResource.askerIdField, userId)], limit, undefined, [Sorts.DESC(ctx.options.sessionResource.createdAtField)]
+      );
+      return {
+        sessions: sessions.map((session) => ({
+          sessionId: session[ctx.options.sessionResource.idField],
+          title: session[ctx.options.sessionResource.titleField],
+          timestamp: session[ctx.options.sessionResource.createdAtField],
+        })),
+      };
+    }
+  });
+
+  server.endpoint({
+    method: 'POST',
+    path: `/agent/get-session-info`,
+    handler: async ({body, adminUser, response }) => {
+      const data = ctx.parseBody(sessionIdBodySchema, body, response);
+      if (!data) return;
+      const userId = adminUser!.pk;
+      const sessionId = data.sessionId;
+      const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
+        [Filters.EQ(ctx.options.sessionResource.idField, sessionId)]
+      );
+      if (!session) {
+        return {
+          error: 'Session not found'
+        };
+      }
+      if (session[ctx.options.sessionResource.askerIdField] !== userId) {
+        return {
+          error: 'Unauthorized'
+        };
+      }
+      const turns = await ctx.getSessionTurns(sessionId);
+      return {
+        session: {
+          sessionId,
+          title: session[ctx.options.sessionResource.titleField],
+          timestamp: session[ctx.options.sessionResource.createdAtField],
+          messages: turns.flatMap(turn => {
+            const messages: Array<{ text: string; role: 'user' | 'assistant' | 'system' }> = [];
+            if (turn.prompt === AGENT_SYSTEM_TURN_PROMPT) {
+              messages.push({
+                text: turn.response,
+                role: 'system',
+              });
+              return messages;
+            }
+            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 = ctx.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 = {
+        [ctx.options.sessionResource.idField]: randomUUID(),
+        [ctx.options.sessionResource.titleField]: title,
+        [ctx.options.sessionResource.askerIdField]: userId,
+      };
+      const { createdRecord } = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).create(newSession);
+      return {
+        sessionId: createdRecord[ctx.options.sessionResource.idField],
+        title: createdRecord[ctx.options.sessionResource.titleField],
+        timestamp: createdRecord[ctx.options.sessionResource.createdAtField],
+        messages: []
+      };
+    }
+  });
+
+  server.endpoint({
+    method: 'POST',
+    path: `/agent/delete-session`,
+    handler: async ({body, adminUser, response }) => {
+      const data = ctx.parseBody(sessionIdBodySchema, body, response);
+      if (!data) return;
+      const sessionId = data.sessionId;
+      const userId = adminUser!.pk;
+      const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
+        [Filters.EQ(ctx.options.sessionResource.idField, sessionId)]
+      );
+      if (!session) {
+        return {
+          error: 'Session not found'
+        };
+      }
+      if (session[ctx.options.sessionResource.askerIdField] !== userId) {
+        return {
+          error: 'Unauthorized'
+        };
+      }
+      await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).delete(sessionId);
+      const turns = await ctx.adminforth.resource(ctx.options.turnResource.resourceId).list(
+        [Filters.EQ(ctx.options.turnResource.sessionIdField, sessionId)]
+      );
+      await Promise.all(turns.map(turn => ctx.adminforth.resource(ctx.options.turnResource.resourceId).delete(turn[ctx.options.turnResource.idField])));
+      return {
+        ok: true
+      };
+    }
+  });
+
+  server.endpoint({
+    method: 'POST',
+    path: `/agent/add-system-message-to-turns`,
+    handler: async ({body, adminUser, response }) => {
+      const data = ctx.parseBody(addSystemMessageBodySchema, body, response);
+      if (!data) return;
+      const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
+        [Filters.EQ(ctx.options.sessionResource.idField, data.sessionId)]
+      );
+      if (!session) {
+        return {
+          error: 'Session not found'
+        };
+      }
+      if (session[ctx.options.sessionResource.askerIdField] !== adminUser!.pk) {
+        return {
+          error: 'Unauthorized'
+        };
+      }
+      await ctx.createSystemTurn(data.sessionId, data.systemMessage);
+      return {
+        ok: true
+      }
+    }
+  })
+}

package/errors.ts

@@ -0,0 +1,10 @@
+export function isAbortError(error: unknown): boolean {
+  return typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error.name === "AbortError" || error.name === "APIUserAbortError");
+}
+
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}