@adminforth/agent 1.43.29 → 1.44.0

package/dist/agentResponseEvents.js

@@ -1,144 +1 @@
-import { randomUUID } from "crypto";
-export function createAgentEventStream(res, options = {}) {
-    let isStreamClosed = false;
-    let activeBlock = null;
-    res.writeHead(200, Object.assign({ "Content-Type": "text/event-stream", "Cache-Control": "no-cache", "Connection": "keep-alive" }, (options.vercelAiUiMessageStream
-        ? { "x-vercel-ai-ui-message-stream": "v1" }
-        : {})));
-    const stream = {
-        send(obj) {
-            if (isStreamClosed || res.writableEnded || res.destroyed) {
-                return;
-            }
-            res.write(`data: ${JSON.stringify(obj)}\n\n`);
-        },
-        endActiveBlock() {
-            if (!activeBlock) {
-                return;
-            }
-            stream.send({
-                type: `${activeBlock.type}-end`,
-                id: activeBlock.id,
-            });
-            activeBlock = null;
-        },
-        startBlock(type) {
-            if ((activeBlock === null || activeBlock === void 0 ? void 0 : activeBlock.type) === type) {
-                return activeBlock.id;
-            }
-            stream.endActiveBlock();
-            const id = randomUUID();
-            activeBlock = { type, id };
-            stream.send({
-                type: `${type}-start`,
-                id,
-            });
-            return id;
-        },
-        start(messageId) {
-            stream.send({
-                type: "start",
-                messageId,
-            });
-        },
-        textDelta(delta) {
-            const textId = stream.startBlock("text");
-            stream.send({
-                type: "text-delta",
-                id: textId,
-                delta,
-            });
-        },
-        reasoningDelta(delta) {
-            const reasoningId = stream.startBlock("reasoning");
-            stream.send({
-                type: "reasoning-delta",
-                id: reasoningId,
-                delta,
-            });
-        },
-        toolCall(event) {
-            if (options.closeActiveBlockOnToolStart && event.phase === "start") {
-                stream.endActiveBlock();
-            }
-            stream.send({
-                type: "data-tool-call",
-                data: event,
-            });
-        },
-        transcript(text, language) {
-            stream.send({
-                type: "transcript",
-                data: {
-                    text,
-                    language,
-                },
-            });
-        },
-        response(text, sessionId, turnId) {
-            stream.send({
-                type: "response",
-                data: {
-                    text,
-                    sessionId,
-                    turnId,
-                },
-            });
-        },
-        speechResponse(transcript, response, sessionId, turnId) {
-            stream.send({
-                type: "speech-response",
-                data: {
-                    transcript,
-                    response,
-                    sessionId,
-                    turnId,
-                },
-            });
-        },
-        audioStart(mimeType, format, sampleRate, channelCount, bitsPerSample) {
-            stream.send({
-                type: "audio-start",
-                data: {
-                    mimeType,
-                    format,
-                    sampleRate,
-                    channelCount,
-                    bitsPerSample,
-                },
-            });
-        },
-        audioDelta(value) {
-            stream.send({
-                type: "audio-delta",
-                data: {
-                    base64: Buffer.from(value).toString("base64"),
-                },
-            });
-        },
-        audioDone() {
-            stream.send({
-                type: "audio-done",
-            });
-        },
-        error(error) {
-            stream.send({
-                type: "error",
-                error,
-            });
-        },
-        end() {
-            if (isStreamClosed || res.writableEnded || res.destroyed) {
-                return;
-            }
-            stream.endActiveBlock();
-            stream.send({
-                type: "finish",
-            });
-            res.write("data: [DONE]\n\n");
-            isStreamClosed = true;
-            res.end();
-        },
-    };
-    return stream;
-}
+export { createSseEventEmitter } from "./surfaces/web-sse/createSseEventEmitter.js";

package/dist/apiBasedTools.d.ts

@@ -0,0 +1,29 @@
+import { type AdminUser, type IAdminForth } from 'adminforth';
+export type ApiBasedToolCallParams = {
+    adminUser?: AdminUser;
+    adminuser?: AdminUser;
+    abortSignal?: AbortSignal;
+    inputs?: Record<string, unknown>;
+    userTimeZone?: string;
+    acceptLanguage?: string;
+};
+export type ApiBasedTool = {
+    description?: string;
+    input_schema?: unknown;
+    output_schema?: unknown;
+    call: (params?: ApiBasedToolCallParams) => Promise<string>;
+};
+export declare function formatApiBasedToolCall(params: {
+    adminforth: IAdminForth;
+    adminUser?: AdminUser;
+    inputs?: Record<string, unknown>;
+    toolName: string;
+    userTimeZone?: string;
+}): Promise<string | undefined>;
+export declare function prepareApiBasedTools(adminforth: IAdminForth, hiddenResourceIds?: Iterable<string>): Record<string, ApiBasedTool>;
+export declare function serializeApiBasedTool(tool: ApiBasedTool | undefined): {
+    description: string | undefined;
+    input_schema: unknown;
+    output_schema: unknown;
+    call: string;
+} | null;

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import type { AdminUser, AdminForthResource, IAdminForth, IHttpServer } from "adminforth";
+import { AdminForthPlugin } from "adminforth";
+import type { PluginOptions } from './types.js';
+import { createSequenceDebugCollector } from "./agent/middleware/sequenceDebug.js";
+import { type PreviousUserMessage } from "./agent/languageDetect.js";
+import type { AgentEventEmitter } from "./agentEvents.js";
+import type { CurrentPageContext } from "./agent/tools/getUserLocation.js";
+export type { AgentEvent, AgentEventEmitter } from "./agentEvents.js";
+type AgentTurnRunInput = {
+    prompt: string;
+    sessionId: string;
+    turnId: string;
+    previousUserMessages: PreviousUserMessage[];
+    modeName?: string | null;
+    userTimeZone: string;
+    currentPage?: CurrentPageContext;
+    abortSignal?: AbortSignal;
+    adminUser: AdminUser;
+    sequenceDebugCollector: ReturnType<typeof createSequenceDebugCollector>;
+    emit?: AgentEventEmitter;
+};
+type RunAndPersistAgentResponseInput = Omit<AgentTurnRunInput, "turnId" | "sequenceDebugCollector" | "previousUserMessages"> & {
+    failureLogMessage: string;
+    abortLogMessage: string;
+};
+type HandleTurnInput = Omit<RunAndPersistAgentResponseInput, "failureLogMessage" | "abortLogMessage"> & {
+    emit: AgentEventEmitter;
+    failureLogMessage?: string;
+    abortLogMessage?: string;
+};
+export default class AdminForthAgentPlugin extends AdminForthPlugin {
+    options: PluginOptions;
+    agentSystemPromptPromise: Promise<string>;
+    private checkpointer;
+    private parseBody;
+    private createNewTurn;
+    private getSessionTurns;
+    private getPreviousUserMessages;
+    private getChatSurfaceSessionId;
+    private getOrCreateChatSurfaceSession;
+    private getCheckpointer;
+    private getInternalAgentResourceIds;
+    constructor(options: PluginOptions);
+    modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource): Promise<void>;
+    validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource): void;
+    instanceUniqueRepresentation(pluginOptions: any): string;
+    private runAgentTurn;
+    private runAndPersistAgentResponse;
+    handleTurn(input: HandleTurnInput): Promise<{
+        text: string;
+        turnId: any;
+        aborted: boolean;
+        failed: boolean;
+    }>;
+    private createChatSurfaceEventEmitter;
+    private handleChatSurfaceMessage;
+    setupEndpoints(server: IHttpServer): void;
+}

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({
@@ -104,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;
@@ -170,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));
     }
@@ -238,7 +260,10 @@ 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,
             });
@@ -271,11 +296,17 @@ 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);
+                        yield ((_j = input.emit) === null || _j === void 0 ? void 0 : _j.call(input, {
+                            type: "text-delta",
+                            delta: textDelta,
+                        }));
                     }
                 }
             }
@@ -293,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, {
@@ -315,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;
             }
@@ -330,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();
@@ -349,7 +377,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 +524,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 +536,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 +563,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 +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({
@@ -463,26 +616,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 +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);
@@ -509,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) {
@@ -526,9 +702,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;
                 }
             })

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