@adminforth/agent 1.45.0 → 1.46.0

package/dist/chatSurfaceService.js

@@ -0,0 +1,265 @@
+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, logger } from "adminforth";
+import { randomUUID } from "crypto";
+import { getErrorMessage, isAbortError } from "./errors.js";
+import { sanitizeSpeechText } from "./sanitizeSpeechText.js";
+const DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD = "externalUserId";
+const CHAT_SURFACE_LINK_TOKEN_TTL_MS = 60 * 1000;
+export class ChatSurfaceService {
+    constructor(getAdminforth, options, sessionStore, handleTurn, runAndPersistAgentResponse) {
+        this.getAdminforth = getAdminforth;
+        this.options = options;
+        this.sessionStore = sessionStore;
+        this.handleTurn = handleTurn;
+        this.runAndPersistAgentResponse = runAndPersistAgentResponse;
+        this.linkTokens = new Map();
+    }
+    getConnectActionAdapters() {
+        var _a;
+        return ((_a = this.options.chatSurfaceAdapters) !== null && _a !== void 0 ? _a : [])
+            .map((adapter) => adapter)
+            .filter((adapter) => adapter.createConnectAction);
+    }
+    createLinkToken(surface, adminUser) {
+        for (const [token, payload] of this.linkTokens) {
+            if (payload.expiresAt <= Date.now()) {
+                this.linkTokens.delete(token);
+            }
+        }
+        const token = randomUUID();
+        this.linkTokens.set(token, {
+            surface,
+            adminUserId: adminUser.pk,
+            expiresAt: Date.now() + CHAT_SURFACE_LINK_TOKEN_TTL_MS,
+        });
+        return token;
+    }
+    consumeLinkToken(surface, token) {
+        const payload = this.linkTokens.get(token);
+        this.linkTokens.delete(token);
+        if (!payload || payload.surface !== surface || payload.expiresAt <= Date.now()) {
+            return null;
+        }
+        return payload;
+    }
+    createEventEmitter(sink) {
+        return (event) => __awaiter(this, void 0, void 0, function* () {
+            if (event.type === "text-delta") {
+                yield sink.emit({
+                    type: "text_delta",
+                    delta: event.delta,
+                });
+                return;
+            }
+            if (event.type === "response") {
+                yield sink.emit({
+                    type: "done",
+                    text: event.text,
+                });
+                return;
+            }
+            if (event.type === "error") {
+                yield sink.emit({
+                    type: "error",
+                    message: event.error,
+                });
+            }
+        });
+    }
+    handleLink(incoming, sink) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            if (((_a = incoming.metadata) === null || _a === void 0 ? void 0 : _a.isStartCommand) !== true) {
+                return false;
+            }
+            const externalUserIdField = (_b = this.options.chatExternalIdsField) !== null && _b !== void 0 ? _b : DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+            const adminforth = this.getAdminforth();
+            const authResourceId = adminforth.config.auth.usersResourceId;
+            const authResource = adminforth.config.resources.find((resource) => resource.resourceId === authResourceId);
+            const primaryKeyField = authResource.columns.find((column) => column.primaryKey).name;
+            const linkedAdminUserRecord = (yield adminforth.resource(authResourceId).list(Filters.IS_NOT_EMPTY(externalUserIdField))).find((user) => { var _a; return ((_a = user[externalUserIdField]) === null || _a === void 0 ? void 0 : _a[incoming.surface]) === incoming.externalUserId; });
+            if (linkedAdminUserRecord) {
+                yield sink.emit({
+                    type: "done",
+                    text: `${incoming.surface} account is already connected to AdminForth.`,
+                });
+                return true;
+            }
+            if (typeof ((_c = incoming.metadata) === null || _c === void 0 ? void 0 : _c.startPayload) !== "string") {
+                yield sink.emit({
+                    type: "done",
+                    text: `Open AdminForth and connect your ${incoming.surface} account from Chat Surfaces settings.`,
+                });
+                return true;
+            }
+            const payload = this.consumeLinkToken(incoming.surface, incoming.metadata.startPayload);
+            if (!payload) {
+                yield sink.emit({
+                    type: "error",
+                    message: "This chat surface link is expired or invalid. Please start linking again from AdminForth.",
+                });
+                return true;
+            }
+            const adminUserRecord = yield adminforth.resource(authResourceId).get([
+                Filters.EQ(primaryKeyField, payload.adminUserId),
+            ]);
+            yield adminforth.resource(authResourceId).update(payload.adminUserId, {
+                [externalUserIdField]: Object.assign(Object.assign({}, ((_d = adminUserRecord[externalUserIdField]) !== null && _d !== void 0 ? _d : {})), { [incoming.surface]: incoming.externalUserId }),
+            });
+            yield sink.emit({
+                type: "done",
+                text: `${incoming.surface} account connected to AdminForth.`,
+            });
+            return true;
+        });
+    }
+    handleAudioMessage(incoming, sink, adminUser) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const audioAdapter = this.options.audioAdapter;
+            if (!audioAdapter) {
+                yield sink.emit({
+                    type: "error",
+                    message: "Audio adapter is not configured for AdminForth Agent.",
+                });
+                return;
+            }
+            let transcription;
+            try {
+                transcription = yield audioAdapter.transcribe({
+                    buffer: incoming.audio.buffer,
+                    filename: incoming.audio.filename,
+                    mimeType: incoming.audio.mimeType,
+                    language: "auto",
+                });
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    logger.info(`Agent ${incoming.surface} surface speech transcription aborted`);
+                    return;
+                }
+                logger.error(`Agent ${incoming.surface} surface speech transcription failed:\n${getErrorMessage(error)}`);
+                yield sink.emit({
+                    type: "error",
+                    message: "Speech transcription failed. Check server logs for details.",
+                });
+                return;
+            }
+            if (!transcription.text) {
+                yield sink.emit({
+                    type: "error",
+                    message: "Speech transcription is empty",
+                });
+                return;
+            }
+            const agentResponse = yield this.handleAgentSurfaceResponse(incoming, sink, adminUser, transcription.text, { emitDone: false });
+            if (!agentResponse || agentResponse.aborted || agentResponse.failed) {
+                return;
+            }
+            yield sink.emit({
+                type: "done",
+                text: agentResponse.text,
+            });
+            try {
+                const speech = yield audioAdapter.synthesize({
+                    text: sanitizeSpeechText(agentResponse.text),
+                    stream: false,
+                    format: "opus",
+                });
+                yield sink.emit({
+                    type: "audio",
+                    audio: speech.audio,
+                    filename: "agent-response.ogg",
+                    mimeType: speech.mimeType,
+                });
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    logger.info(`Agent ${incoming.surface} surface speech synthesis aborted`);
+                    return;
+                }
+                logger.error(`Agent ${incoming.surface} surface speech synthesis failed:\n${getErrorMessage(error)}`);
+                yield sink.emit({
+                    type: "error",
+                    message: getErrorMessage(error),
+                });
+            }
+        });
+    }
+    handleAgentSurfaceResponse(incoming, sink, adminUser, prompt, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const emitDone = (_a = options === null || options === void 0 ? void 0 : options.emitDone) !== null && _a !== void 0 ? _a : true;
+            const sessionId = yield this.sessionStore.getOrCreateChatSurfaceSession(Object.assign(Object.assign({}, incoming), { prompt }), adminUser);
+            if (emitDone) {
+                yield this.handleTurn({
+                    prompt,
+                    sessionId,
+                    modeName: incoming.modeName,
+                    userTimeZone: (_b = incoming.userTimeZone) !== null && _b !== void 0 ? _b : "UTC",
+                    adminUser,
+                    emit: this.createEventEmitter(sink),
+                    failureLogMessage: `Agent ${incoming.surface} surface response failed`,
+                    abortLogMessage: `Agent ${incoming.surface} surface response aborted`,
+                });
+                return null;
+            }
+            const agentResponse = yield this.runAndPersistAgentResponse({
+                prompt,
+                sessionId,
+                modeName: incoming.modeName,
+                userTimeZone: (_c = incoming.userTimeZone) !== null && _c !== void 0 ? _c : "UTC",
+                adminUser,
+                emit: this.createEventEmitter(sink),
+                failureLogMessage: `Agent ${incoming.surface} surface response failed`,
+                abortLogMessage: `Agent ${incoming.surface} surface response aborted`,
+            });
+            if (agentResponse.failed) {
+                yield sink.emit({
+                    type: "error",
+                    message: agentResponse.text,
+                });
+            }
+            return agentResponse;
+        });
+    }
+    handleMessage(adapter, incoming, sink) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (yield this.handleLink(incoming, sink)) {
+                return;
+            }
+            const adminforth = this.getAdminforth();
+            const authResourceId = adminforth.config.auth.usersResourceId;
+            const authResource = adminforth.config.resources.find((resource) => resource.resourceId === authResourceId);
+            const primaryKeyField = authResource.columns.find((column) => column.primaryKey).name;
+            const externalUserIdField = (_a = this.options.chatExternalIdsField) !== null && _a !== void 0 ? _a : DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+            const adminUserRecord = (yield adminforth.resource(authResourceId).list(Filters.IS_NOT_EMPTY(externalUserIdField))).find((user) => { var _a; return ((_a = user[externalUserIdField]) === null || _a === void 0 ? void 0 : _a[adapter.name]) === incoming.externalUserId; });
+            if (!adminUserRecord) {
+                yield sink.emit({
+                    type: "error",
+                    message: "This chat account is not authorized to use AdminForth Agent.",
+                });
+                return;
+            }
+            const adminUser = {
+                pk: adminUserRecord[primaryKeyField],
+                username: adminUserRecord[adminforth.config.auth.usernameField],
+                dbUser: adminUserRecord,
+            };
+            const incomingWithAudio = incoming;
+            if (incomingWithAudio.audio) {
+                yield this.handleAudioMessage(incomingWithAudio, sink, adminUser);
+                return;
+            }
+            yield this.handleAgentSurfaceResponse(incoming, sink, adminUser, incoming.prompt);
+        });
+    }
+}

package/dist/endpoints/chatSurfaces.d.ts

@@ -0,0 +1,3 @@
+import type { IHttpServer } from "adminforth";
+import type { ChatSurfaceEndpointsContext } from "./context.js";
+export declare function setupChatSurfaceEndpoints(ctx: ChatSurfaceEndpointsContext, server: IHttpServer): void;

package/dist/endpoints/chatSurfaces.js

@@ -0,0 +1,91 @@
+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());
+    });
+};
+const DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD = "externalUserId";
+export function setupChatSurfaceEndpoints(ctx, server) {
+    var _a;
+    if (ctx.getChatSurfaceConnectActionAdapters().length) {
+        server.endpoint({
+            method: "POST",
+            path: "/agent/surfaces/connectable",
+            handler: (_a) => __awaiter(this, [_a], void 0, function* ({ adminUser }) {
+                var _b, _c;
+                const externalUserIdField = (_b = ctx.options.chatExternalIdsField) !== null && _b !== void 0 ? _b : DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+                const externalIds = (_c = adminUser.dbUser[externalUserIdField]) !== null && _c !== void 0 ? _c : {};
+                return {
+                    surfaces: ctx.getChatSurfaceConnectActionAdapters().map((adapter) => {
+                        var _a;
+                        return ({
+                            name: adapter.name,
+                            externalUserId: (_a = externalIds[adapter.name]) !== null && _a !== void 0 ? _a : null,
+                        });
+                    }),
+                };
+            }),
+        });
+    }
+    for (const adapter of (_a = ctx.options.chatSurfaceAdapters) !== null && _a !== void 0 ? _a : []) {
+        const connectActionAdapter = adapter;
+        if (connectActionAdapter.createConnectAction) {
+            server.endpoint({
+                method: "POST",
+                path: `/agent/surface/${adapter.name}/connect-action`,
+                handler: (_a) => __awaiter(this, [_a], void 0, function* ({ adminUser }) {
+                    const token = ctx.createChatSurfaceLinkToken(adapter.name, adminUser);
+                    const action = yield connectActionAdapter.createConnectAction({ token });
+                    return {
+                        action,
+                    };
+                }),
+            });
+            server.endpoint({
+                method: "POST",
+                path: `/agent/surface/${adapter.name}/disconnect`,
+                handler: (_a) => __awaiter(this, [_a], void 0, function* ({ adminUser }) {
+                    var _b, _c;
+                    const externalUserIdField = (_b = ctx.options.chatExternalIdsField) !== null && _b !== void 0 ? _b : DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+                    const externalIds = Object.assign({}, ((_c = adminUser.dbUser[externalUserIdField]) !== null && _c !== void 0 ? _c : {}));
+                    delete externalIds[adapter.name];
+                    yield 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: (endpointInput) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const surfaceContext = {
+                    body: endpointInput.body,
+                    headers: endpointInput.headers,
+                    abortSignal: endpointInput.abortSignal,
+                    rawRequest: endpointInput._raw_express_req,
+                    rawResponse: endpointInput._raw_express_res,
+                };
+                const incoming = yield adapter.parseIncomingMessage(surfaceContext);
+                if (!incoming)
+                    return { ok: true };
+                const sink = yield adapter.createEventSink(surfaceContext, incoming);
+                try {
+                    yield ctx.handleChatSurfaceMessage(adapter, incoming, sink);
+                }
+                finally {
+                    yield ((_a = sink.close) === null || _a === void 0 ? void 0 : _a.call(sink));
+                }
+                return { ok: true };
+            }),
+        });
+    }
+}

package/dist/endpoints/context.d.ts

@@ -0,0 +1,30 @@
+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/dist/endpoints/context.js

@@ -0,0 +1 @@
+export {};

package/dist/endpoints/core.d.ts

@@ -0,0 +1,3 @@
+import type { IHttpServer } from "adminforth";
+import type { CoreEndpointsContext } from "./context.js";
+export declare function setupCoreEndpoints(ctx: CoreEndpointsContext, server: IHttpServer): void;

package/dist/endpoints/core.js

@@ -0,0 +1,106 @@
+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 { z } from "zod";
+import { createSseEventEmitter } from "../surfaces/web-sse/createSseEventEmitter.js";
+const agentResponseBodySchema = z.object({
+    message: z.string(),
+    sessionId: z.string(),
+    mode: z.string().nullish(),
+    timeZone: z.string().optional(),
+    currentPage: z.custom().optional(),
+}).strict();
+const agentSpeechResponseBodySchema = agentResponseBodySchema.omit({ message: true });
+export function setupCoreEndpoints(ctx, server) {
+    server.endpoint({
+        method: 'POST',
+        path: `/agent/get-placeholder-messages`,
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ headers, adminUser }) {
+            if (!ctx.options.placeholderMessages) {
+                return {
+                    messages: [],
+                };
+            }
+            const messages = yield ctx.options.placeholderMessages({
+                adminUser: adminUser,
+                headers,
+            });
+            return {
+                messages,
+            };
+        })
+    });
+    server.endpoint({
+        method: 'POST',
+        path: `/agent/response`,
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, _raw_express_res, abortSignal }) {
+            var _b;
+            const data = ctx.parseBody(agentResponseBodySchema, body, response);
+            if (!data)
+                return;
+            const emit = createSseEventEmitter(_raw_express_res, {
+                vercelAiUiMessageStream: true,
+                closeActiveBlockOnToolStart: true,
+            });
+            yield ctx.handleTurn({
+                prompt: data.message,
+                sessionId: data.sessionId,
+                modeName: data.mode,
+                userTimeZone: (_b = data.timeZone) !== null && _b !== void 0 ? _b : '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: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, _raw_express_req, _raw_express_res, abortSignal }) {
+            var _b;
+            const req = _raw_express_req;
+            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);
+            yield ctx.handleSpeechTurn({
+                audioAdapter,
+                audio: {
+                    buffer: req.file.buffer,
+                    filename: req.file.originalname,
+                    mimeType: req.file.mimetype,
+                },
+                sessionId: data.sessionId,
+                modeName: data.mode,
+                userTimeZone: (_b = data.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
+                currentPage: data.currentPage,
+                abortSignal,
+                adminUser: adminUser,
+                emit,
+                failureLogMessage: "Agent speech response failed",
+                abortLogMessage: "Agent speech response aborted by the client",
+            });
+            return null;
+        })
+    });
+}

package/dist/endpoints/sessions.d.ts

@@ -0,0 +1,3 @@
+import type { IHttpServer } from "adminforth";
+import type { SessionEndpointsContext } from "./context.js";
+export declare function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHttpServer): void;