@adminforth/agent 1.43.29 → 1.44.1

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({
@@ -48,6 +48,8 @@ const sessionIdBodySchema = z.object({
 const createSessionBodySchema = z.object({
     triggerMessage: z.string().optional(),
 }).strict();
+const VEGA_LITE_FENCE_START = "```vega-lite";
+const COMPLETE_VEGA_LITE_BLOCK_RE = /```vega-lite[\s\S]*?```/;
 function isAbortError(error) {
     return (error instanceof DOMException && error.name === "AbortError") || (typeof error === "object" &&
         error !== null &&
@@ -104,6 +106,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;
@@ -170,8 +191,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));
     }
@@ -181,8 +205,10 @@ 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, _j;
+            var _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
             let fullResponse = "";
+            let bufferedTextDelta = "";
+            let isRenderingVegaLite = false;
             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];
             const [primaryModelSpec, summaryModelSpec] = yield Promise.all([
@@ -238,14 +264,17 @@ 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 _k = true, _l = __asyncValues(stream), _m; _m = yield _l.next(), _a = _m.done, !_a; _k = true) {
-                    _c = _m.value;
-                    _k = false;
+                for (var _p = true, _q = __asyncValues(stream), _r; _r = yield _q.next(), _a = _r.done, !_a; _p = true) {
+                    _c = _r.value;
+                    _p = false;
                     const rawChunk = _c;
                     if ((_g = input.abortSignal) === null || _g === void 0 ? void 0 : _g.aborted) {
                         throw new DOMException("This operation was aborted", "AbortError");
@@ -271,21 +300,68 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                         .map((b) => { var _a; return String((_a = b.text) !== null && _a !== void 0 ? _a : ""); })
                         .join("");
                     if (reasoningDelta) {
-                        (_h = input.emitReasoningDelta) === null || _h === void 0 ? void 0 : _h.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;
-                        (_j = input.emitTextDelta) === null || _j === void 0 ? void 0 : _j.call(input, textDelta);
+                        bufferedTextDelta += textDelta;
+                        if (bufferedTextDelta.includes(VEGA_LITE_FENCE_START) &&
+                            !COMPLETE_VEGA_LITE_BLOCK_RE.test(bufferedTextDelta)) {
+                            if (!isRenderingVegaLite) {
+                                isRenderingVegaLite = true;
+                                yield ((_j = input.emit) === null || _j === void 0 ? void 0 : _j.call(input, {
+                                    type: "rendering",
+                                    phase: "start",
+                                    label: "Rendering...",
+                                }));
+                            }
+                            continue;
+                        }
+                        if (isRenderingVegaLite) {
+                            isRenderingVegaLite = false;
+                            yield ((_k = input.emit) === null || _k === void 0 ? void 0 : _k.call(input, {
+                                type: "rendering",
+                                phase: "end",
+                                label: "Rendering...",
+                            }));
+                        }
+                        const streamableLength = bufferedTextDelta.includes(VEGA_LITE_FENCE_START)
+                            ? bufferedTextDelta.length
+                            : bufferedTextDelta.length - getPartialVegaLiteFenceStartLength(bufferedTextDelta);
+                        if (!streamableLength) {
+                            continue;
+                        }
+                        yield ((_l = input.emit) === null || _l === void 0 ? void 0 : _l.call(input, {
+                            type: "text-delta",
+                            delta: bufferedTextDelta.slice(0, streamableLength),
+                        }));
+                        bufferedTextDelta = bufferedTextDelta.slice(streamableLength);
                     }
                 }
             }
             catch (e_1_1) { e_1 = { error: e_1_1 }; }
             finally {
                 try {
-                    if (!_k && !_a && (_b = _l.return)) yield _b.call(_l);
+                    if (!_p && !_a && (_b = _q.return)) yield _b.call(_q);
                 }
                 finally { if (e_1) throw e_1.error; }
             }
+            if (isRenderingVegaLite) {
+                yield ((_m = input.emit) === null || _m === void 0 ? void 0 : _m.call(input, {
+                    type: "rendering",
+                    phase: "end",
+                    label: "Rendering...",
+                }));
+            }
+            if (bufferedTextDelta) {
+                yield ((_o = input.emit) === null || _o === void 0 ? void 0 : _o.call(input, {
+                    type: "text-delta",
+                    delta: bufferedTextDelta,
+                }));
+            }
             return {
                 text: fullResponse,
             };
@@ -293,7 +369,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, {
@@ -315,9 +391,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;
             }
@@ -330,7 +404,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();
@@ -349,7 +422,125 @@ 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`,
@@ -378,10 +569,11 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                 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,
@@ -389,14 +581,10 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     currentPage: data.currentPage,
                     abortSignal,
                     adminUser: currentAdminUser,
-                    emitToolCallEvent: stream.toolCall,
-                    emitReasoningDelta: stream.reasoningDelta,
-                    emitTextDelta: stream.textDelta,
-                    emitErrorResponse: stream.textDelta,
+                    emit,
                     failureLogMessage: "Agent response streaming failed",
                     abortLogMessage: "Agent response streaming aborted by the client",
                 });
-                stream.end();
                 return null;
             })
         });
@@ -420,7 +608,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     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({
@@ -434,25 +622,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({
@@ -463,26 +661,39 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     currentPage,
                     abortSignal,
                     adminUser: currentAdminUser,
-                    emitToolCallEvent: stream.toolCall,
+                    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,
@@ -490,7 +701,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);
@@ -509,15 +727,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) {
@@ -526,9 +747,12 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     }
                     else {
                         logger.error(`Agent speech audio streaming failed:\n${error}`);
-                        stream.error(getErrorMessage(error));
+                        yield emit({
+                            type: "error",
+                            error: getErrorMessage(error),
+                        });
                     }
-                    stream.end();
+                    yield emit({ type: "finish" });
                     return null;
                 }
             })
@@ -674,3 +898,11 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             });
     }
 }
+function getPartialVegaLiteFenceStartLength(text) {
+    for (let length = Math.min(text.length, VEGA_LITE_FENCE_START.length - 1); length > 0; length -= 1) {
+        if (VEGA_LITE_FENCE_START.startsWith(text.slice(-length))) {
+            return length;
+        }
+    }
+    return 0;
+}

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 {};