@adminforth/agent 1.43.28 → 1.44.0

package/dist/index.js

@@ -24,7 +24,7 @@ import { AdminForthCheckpointSaver } from "./agent/checkpointer.js";
 import { createSequenceDebugCollector } from "./agent/middleware/sequenceDebug.js";
 import { detectUserLanguage } from "./agent/languageDetect.js";
 import { prepareApiBasedTools as buildApiBasedTools } from './apiBasedTools.js';
-import { createAgentEventStream } from "./agentResponseEvents.js";
+import { createSseEventEmitter } from "./surfaces/web-sse/createSseEventEmitter.js";
 import { appendCustomSystemPrompt, buildAgentSystemPrompt, buildAgentTurnSystemPrompt, DEFAULT_AGENT_SYSTEM_PROMPT } from "./agent/systemPrompt.js";
 import { sanitizeSpeechText } from "./sanitizeSpeechText.js";
 const agentResponseBodySchema = z.object({
@@ -57,6 +57,12 @@ function isAbortError(error) {
 function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function requireAdminUser(adminUser) {
+    if (!adminUser) {
+        throw new Error("AdminForth Agent endpoint requires an authenticated admin user");
+    }
+    return adminUser;
+}
 export default class AdminForthAgentPlugin extends AdminForthPlugin {
     parseBody(schema, body, response) {
         const parsed = schema.safeParse(body !== null && body !== void 0 ? body : {});
@@ -98,6 +104,25 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             }));
         });
     }
+    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.adminforth.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;
+        });
+    }
     getCheckpointer() {
         if (this.checkpointer)
             return this.checkpointer;
@@ -164,8 +189,11 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         });
     }
     validateConfigAfterDiscover(adminforth, resourceConfig) {
-        var _a;
+        var _a, _b;
         (_a = this.options.audioAdapter) === null || _a === void 0 ? void 0 : _a.validate();
+        for (const chatSurfaceAdapter of (_b = this.options.chatSurfaceAdapters) !== null && _b !== void 0 ? _b : []) {
+            chatSurfaceAdapter.validate();
+        }
         this.agentSystemPromptPromise = buildAgentSystemPrompt(adminforth, this.getInternalAgentResourceIds())
             .then((systemPrompt) => appendCustomSystemPrompt(systemPrompt, this.options.systemPrompt));
     }
@@ -175,7 +203,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     runAgentTurn(input) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, e_1, _b, _c;
-            var _d, _e, _f, _g, _h;
+            var _d, _e, _f, _g, _h, _j;
             let fullResponse = "";
             const maxTokens = (_d = this.options.maxTokens) !== null && _d !== void 0 ? _d : 1000;
             const selectedMode = (_e = this.options.modes.find((mode) => mode.name === input.modeName)) !== null && _e !== void 0 ? _e : this.options.modes[0];
@@ -223,7 +251,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                 adminUser: input.adminUser,
                 adminforth: this.adminforth,
                 apiBasedTools,
-                customComponentsDir: this.adminforth.config.customization.customComponentsDir,
+                customComponentsDir: (_f = this.adminforth.config.customization.customComponentsDir) !== null && _f !== void 0 ? _f : "custom",
                 sessionId: input.sessionId,
                 turnId: input.turnId,
                 currentPage: input.currentPage,
@@ -232,16 +260,19 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                 emitToolCallEvent: (event) => {
                     var _a;
                     input.sequenceDebugCollector.handleToolCallEvent(event);
-                    (_a = input.emitToolCallEvent) === null || _a === void 0 ? void 0 : _a.call(input, event);
+                    void ((_a = input.emit) === null || _a === void 0 ? void 0 : _a.call(input, {
+                        type: "tool-call",
+                        data: event,
+                    }));
                 },
                 sequenceDebugSink: input.sequenceDebugCollector,
             });
             try {
-                for (var _j = true, _k = __asyncValues(stream), _l; _l = yield _k.next(), _a = _l.done, !_a; _j = true) {
-                    _c = _l.value;
-                    _j = false;
+                for (var _k = true, _l = __asyncValues(stream), _m; _m = yield _l.next(), _a = _m.done, !_a; _k = true) {
+                    _c = _m.value;
+                    _k = false;
                     const rawChunk = _c;
-                    if ((_f = input.abortSignal) === null || _f === void 0 ? void 0 : _f.aborted) {
+                    if ((_g = input.abortSignal) === null || _g === void 0 ? void 0 : _g.aborted) {
                         throw new DOMException("This operation was aborted", "AbortError");
                     }
                     const [token, metadata] = rawChunk;
@@ -265,18 +296,24 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                         .map((b) => { var _a; return String((_a = b.text) !== null && _a !== void 0 ? _a : ""); })
                         .join("");
                     if (reasoningDelta) {
-                        (_g = input.emitReasoningDelta) === null || _g === void 0 ? void 0 : _g.call(input, reasoningDelta);
+                        yield ((_h = input.emit) === null || _h === void 0 ? void 0 : _h.call(input, {
+                            type: "reasoning-delta",
+                            delta: reasoningDelta,
+                        }));
                     }
                     if (textDelta) {
                         fullResponse += textDelta;
-                        (_h = input.emitTextDelta) === null || _h === void 0 ? void 0 : _h.call(input, textDelta);
+                        yield ((_j = input.emit) === null || _j === void 0 ? void 0 : _j.call(input, {
+                            type: "text-delta",
+                            delta: textDelta,
+                        }));
                     }
                 }
             }
             catch (e_1_1) { e_1 = { error: e_1_1 }; }
             finally {
                 try {
-                    if (!_j && !_a && (_b = _k.return)) yield _b.call(_k);
+                    if (!_k && !_a && (_b = _l.return)) yield _b.call(_l);
                 }
                 finally { if (e_1) throw e_1.error; }
             }
@@ -287,7 +324,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     }
     runAndPersistAgentResponse(input) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a;
             const previousUserMessages = yield this.getPreviousUserMessages(input.sessionId);
             const turnId = yield this.createNewTurn(input.sessionId, input.prompt);
             yield this.adminforth.resource(this.options.sessionResource.resourceId).update(input.sessionId, {
@@ -309,9 +346,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;
             }
@@ -324,7 +359,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     failed = true;
                     fullResponse = getErrorMessage(error);
                     logger.error(`${input.failureLogMessage}:\n${fullResponse}`);
-                    (_b = input.emitErrorResponse) === null || _b === void 0 ? void 0 : _b.call(input, fullResponse);
                 }
             }
             sequenceDebugCollector.flush();
@@ -343,18 +377,137 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             };
         });
     }
+    handleTurn(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            yield input.emit({
+                type: "turn-started",
+                messageId: randomUUID(),
+            });
+            const agentResponse = yield 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: (_a = input.failureLogMessage) !== null && _a !== void 0 ? _a : "Agent response failed",
+                abortLogMessage: (_b = input.abortLogMessage) !== null && _b !== void 0 ? _b : "Agent response aborted",
+            });
+            if (agentResponse.failed) {
+                yield input.emit({
+                    type: "error",
+                    error: agentResponse.text,
+                });
+            }
+            else if (!agentResponse.aborted) {
+                yield input.emit({
+                    type: "response",
+                    text: agentResponse.text,
+                    sessionId: input.sessionId,
+                    turnId: agentResponse.turnId,
+                });
+            }
+            yield input.emit({
+                type: "finish",
+            });
+            return agentResponse;
+        });
+    }
+    createChatSurfaceEventEmitter(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,
+                });
+            }
+        });
+    }
+    handleChatSurfaceMessage(adapter, incoming, sink) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const adminUser = yield adapter.resolveAdminUser({
+                adminforth: this.adminforth,
+                incoming,
+            });
+            if (!adminUser) {
+                yield sink.emit({
+                    type: "error",
+                    message: "This chat account is not authorized to use AdminForth Agent.",
+                });
+                return;
+            }
+            yield this.handleTurn({
+                prompt: incoming.prompt,
+                sessionId: yield this.getOrCreateChatSurfaceSession(incoming, adminUser),
+                modeName: incoming.modeName,
+                userTimeZone: (_a = incoming.userTimeZone) !== null && _a !== void 0 ? _a : "UTC",
+                adminUser,
+                emit: this.createChatSurfaceEventEmitter(sink),
+                failureLogMessage: `Agent ${incoming.surface} surface response failed`,
+                abortLogMessage: `Agent ${incoming.surface} surface response aborted`,
+            });
+        });
+    }
     setupEndpoints(server) {
+        var _a;
+        for (const adapter of (_a = this.options.chatSurfaceAdapters) !== null && _a !== void 0 ? _a : []) {
+            server.endpoint({
+                method: "POST",
+                noAuth: true,
+                path: `/agent/surface/${adapter.name}/webhook`,
+                handler: (ctx) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    const surfaceContext = {
+                        body: ctx.body,
+                        headers: ctx.headers,
+                        abortSignal: ctx.abortSignal,
+                        rawRequest: ctx._raw_express_req,
+                        rawResponse: ctx._raw_express_res,
+                    };
+                    const incoming = yield adapter.parseIncomingMessage(surfaceContext);
+                    if (!incoming)
+                        return { ok: true };
+                    const sink = yield adapter.createEventSink(surfaceContext, incoming);
+                    try {
+                        yield this.handleChatSurfaceMessage(adapter, incoming, sink);
+                    }
+                    finally {
+                        yield ((_a = sink.close) === null || _a === void 0 ? void 0 : _a.call(sink));
+                    }
+                    return { ok: true };
+                }),
+            });
+        }
         server.endpoint({
             method: 'POST',
             path: `/agent/get-placeholder-messages`,
             handler: (_a) => __awaiter(this, [_a], void 0, function* ({ headers, adminUser }) {
+                const currentAdminUser = requireAdminUser(adminUser);
                 if (!this.options.placeholderMessages) {
                     return {
                         messages: [],
                     };
                 }
                 const messages = yield this.options.placeholderMessages({
-                    adminUser,
+                    adminUser: currentAdminUser,
                     headers,
                 });
                 return {
@@ -367,28 +520,26 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             path: `/agent/response`,
             handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, _raw_express_res, abortSignal }) {
                 var _b;
+                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();
-                stream.start(messageId);
-                yield this.runAndPersistAgentResponse({
+                const emit = createSseEventEmitter(_raw_express_res, {
+                    vercelAiUiMessageStream: true,
+                    closeActiveBlockOnToolStart: true,
+                });
+                yield this.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,
-                    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;
             })
         });
@@ -398,20 +549,21 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             target: 'upload',
             handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, _raw_express_req, _raw_express_res, abortSignal }) {
                 var _b;
+                const currentAdminUser = requireAdminUser(adminUser);
                 const req = _raw_express_req;
                 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;
                 try {
                     transcription = yield audioAdapter.transcribe({
@@ -425,25 +577,35 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                 catch (error) {
                     if (abortSignal.aborted || isAbortError(error)) {
                         logger.info("Agent speech transcription aborted by the client");
-                        stream.end();
+                        yield 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();
+                    yield emit({
+                        type: "error",
+                        error: "Speech transcription failed. Check server logs for details.",
+                    });
+                    yield emit({ type: "finish" });
                     return null;
                 }
                 if (abortSignal.aborted) {
-                    stream.end();
+                    yield emit({ type: "finish" });
                     return null;
                 }
                 const prompt = transcription.text;
                 if (!prompt) {
-                    stream.error("Speech transcription is empty");
-                    stream.end();
+                    yield emit({
+                        type: "error",
+                        error: "Speech transcription is empty",
+                    });
+                    yield emit({ type: "finish" });
                     return null;
                 }
-                stream.transcript(transcription.text, transcription.language);
+                yield emit({
+                    type: "transcript",
+                    text: transcription.text,
+                    language: transcription.language,
+                });
                 const sessionId = data.sessionId;
                 const currentPage = data.currentPage;
                 const agentResponse = yield this.runAndPersistAgentResponse({
@@ -453,27 +615,40 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     userTimeZone: (_b = data.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
                     currentPage,
                     abortSignal,
-                    adminUser,
-                    emitToolCallEvent: stream.toolCall,
+                    adminUser: currentAdminUser,
+                    emit: (event) => __awaiter(this, void 0, void 0, function* () {
+                        if (event.type === "tool-call") {
+                            yield emit(event);
+                        }
+                    }),
                     failureLogMessage: "Agent speech response failed",
                     abortLogMessage: "Agent speech response aborted by the client",
                 });
                 if (agentResponse.aborted) {
-                    stream.end();
+                    yield emit({ type: "finish" });
                     return null;
                 }
                 if (agentResponse.failed) {
-                    stream.error(agentResponse.text);
-                    stream.end();
+                    yield emit({
+                        type: "error",
+                        error: agentResponse.text,
+                    });
+                    yield emit({ type: "finish" });
                     return null;
                 }
                 try {
-                    stream.speechResponse({
-                        text: transcription.text,
-                        language: transcription.language,
-                    }, {
-                        text: agentResponse.text,
-                    }, sessionId, agentResponse.turnId);
+                    yield emit({
+                        type: "speech-response",
+                        transcript: {
+                            text: transcription.text,
+                            language: transcription.language,
+                        },
+                        response: {
+                            text: agentResponse.text,
+                        },
+                        sessionId,
+                        turnId: agentResponse.turnId,
+                    });
                     const speech = yield audioAdapter.synthesize({
                         text: sanitizeSpeechText(agentResponse.text),
                         stream: true,
@@ -481,7 +656,14 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                         format: "pcm",
                         abortSignal,
                     });
-                    stream.audioStart(speech.mimeType, speech.format, 24000, 1, 16);
+                    yield 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);
@@ -500,15 +682,18 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                             if (abortSignal.aborted) {
                                 break;
                             }
-                            stream.audioDelta(value);
+                            yield emit({
+                                type: "audio-delta",
+                                value,
+                            });
                         }
                     }
                     finally {
                         abortSignal.removeEventListener("abort", cancelAudioStream);
                         reader.releaseLock();
                     }
-                    stream.audioDone();
-                    stream.end();
+                    yield emit({ type: "audio-done" });
+                    yield emit({ type: "finish" });
                     return null;
                 }
                 catch (error) {
@@ -517,9 +702,12 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     }
                     else {
                         logger.error(`Agent speech audio streaming failed:\n${error}`);
-                        stream.error(error);
+                        yield emit({
+                            type: "error",
+                            error: getErrorMessage(error),
+                        });
                     }
-                    stream.end();
+                    yield emit({ type: "finish" });
                     return null;
                 }
             })
@@ -529,10 +717,11 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             path: `/agent/get-sessions`,
             handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
                 var _b;
+                const currentAdminUser = requireAdminUser(adminUser);
                 const data = this.parseBody(getSessionsBodySchema, body, response);
                 if (!data)
                     return;
-                const userId = adminUser.pk;
+                const userId = currentAdminUser.pk;
                 const limit = (_b = data.limit) !== null && _b !== void 0 ? _b : 20;
                 const sessions = yield this.adminforth.resource(this.options.sessionResource.resourceId).list([Filters.EQ(this.options.sessionResource.askerIdField, userId)], limit, undefined, [Sorts.DESC(this.options.sessionResource.createdAtField)]);
                 return {
@@ -548,12 +737,13 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             method: 'POST',
             path: `/agent/get-session-info`,
             handler: (_a) => __awaiter(this, [_a], void 0, function* ({ 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 = yield this.adminforth.resource(this.options.sessionResource.resourceId).get([Filters.EQ(this.options.sessionResource.idField, sessionId)]);
                 if (!session) {
@@ -596,11 +786,12 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             method: 'POST',
             path: `/agent/create-session`,
             handler: (_a) => __awaiter(this, [_a], void 0, function* ({ 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 === null || triggerMessage === void 0 ? void 0 : triggerMessage.slice(0, 40)) || "New Session";
                 const newSession = {
                     [this.options.sessionResource.idField]: randomUUID(),
@@ -620,11 +811,12 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             method: 'POST',
             path: `/agent/delete-session`,
             handler: (_a) => __awaiter(this, [_a], void 0, function* ({ 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 = yield this.adminforth.resource(this.options.sessionResource.resourceId).get([Filters.EQ(this.options.sessionResource.idField, sessionId)]);
                 if (!session) {
                     return {

package/dist/sanitizeSpeechText.d.ts

@@ -0,0 +1 @@
+export declare function sanitizeSpeechText(input: string): string;

package/dist/surfaces/web-sse/createSseEventEmitter.d.ts

@@ -0,0 +1,14 @@
+import type { AgentEventEmitter } from "../../agentEvents.js";
+type AgentEventStreamResponse = {
+    writeHead: (statusCode: number, headers: Record<string, string>) => void;
+    write: (chunk: string) => unknown;
+    end: () => unknown;
+    writableEnded: boolean;
+    destroyed: boolean;
+};
+type AgentEventStreamOptions = {
+    vercelAiUiMessageStream?: boolean;
+    closeActiveBlockOnToolStart?: boolean;
+};
+export declare function createSseEventEmitter(res: AgentEventStreamResponse, options?: AgentEventStreamOptions): AgentEventEmitter;
+export {};