@adminforth/agent 1.44.2 → 1.45.0

package/build.log

@@ -7,6 +7,7 @@ custom/
 custom/ChatFooter.vue
 custom/ChatHeader.vue
 custom/ChatSurface.vue
+custom/ChatSurfaceSettings.vue
 custom/CustomAutoScrollContainer.vue
 custom/SessionsHistory.vue
 custom/chat.ts
@@ -62,5 +63,5 @@ custom/speech_recognition_frontend/voiceActivityDetection.ts
 custom/speech_recognition_frontend/types/
 custom/speech_recognition_frontend/types/voice-activity-detection.d.ts
 
-sent 1,667,675 bytes  received 921 bytes  3,337,192.00 bytes/sec
-total size is 1,663,522  speedup is 1.00
+sent 1,671,609 bytes  received 940 bytes  3,345,098.00 bytes/sec
+total size is 1,667,436  speedup is 1.00

package/custom/ChatSurfaceSettings.vue

@@ -0,0 +1,125 @@
+<template>
+  <div class="flex flex-col justify-center mr-6 md:mr-12">
+    <h2 class="flex items-start justify-start leading-none text-gray-800 dark:text-gray-50 text-3xl font-semibold">
+      {{ $t('Chat Surfaces') }}
+    </h2>
+    <p class="text-sm mt-3">
+      {{ $t('Connect external chat accounts to your AdminForth user') }}
+    </p>
+
+    <div class="mt-6 flex flex-wrap gap-4">
+      <div
+        v-for="surface in surfaces"
+        :key="surface.name"
+        class="flex flex-col w-full lg:w-72 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl p-4 shadow-sm"
+      >
+        <div class="flex items-center justify-between gap-3 mb-4">
+          <div class="min-w-0">
+            <p class="font-semibold text-gray-900 dark:text-white truncate">
+              {{ formatSurfaceName(surface.name) }}
+            </p>
+            <p class="text-xs text-gray-500 dark:text-gray-400">
+              {{ surface.externalUserId || $t('Not connected') }}
+            </p>
+          </div>
+          <span
+            class="shrink-0 inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium"
+            :class="surface.externalUserId
+              ? 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200'
+              : 'bg-gray-100 text-gray-700 dark:bg-gray-700 dark:text-gray-300'"
+          >
+            {{ surface.externalUserId ? $t('Active') : $t('Inactive') }}
+          </span>
+        </div>
+
+        <div class="grid gap-2 mt-auto" :class="surface.externalUserId ? 'grid-cols-2' : 'grid-cols-1'">
+          <Button
+            class="w-full"
+            :disabled="isSurfaceBusy(surface.name)"
+            :loader="connectingSurfaceName === surface.name"
+            @click="connectSurface(surface.name)"
+          >
+            {{ surface.externalUserId ? $t('Reconnect') : $t('Connect') }}
+          </Button>
+          <Button
+            v-if="surface.externalUserId"
+            class="w-full"
+            :disabled="isSurfaceBusy(surface.name)"
+            :loader="disconnectingSurfaceName === surface.name"
+            @click="disconnectSurface(surface.name)"
+          >
+            {{ $t('Disconnect') }}
+          </Button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { Button } from '@/afcl';
+import { callAdminForthApi } from '@/utils';
+
+type ChatSurface = {
+  name: string;
+  externalUserId: string | null;
+};
+
+const surfaces = ref<ChatSurface[]>([]);
+const connectingSurfaceName = ref<string | null>(null);
+const disconnectingSurfaceName = ref<string | null>(null);
+
+onMounted(loadSurfaces);
+
+async function loadSurfaces() {
+  const response = await callAdminForthApi({
+    method: 'POST',
+    path: '/agent/surfaces/connectable',
+    body: {},
+  });
+
+  surfaces.value = response.surfaces;
+}
+
+async function connectSurface(surfaceName: string) {
+  connectingSurfaceName.value = surfaceName;
+
+  try {
+    const response = await callAdminForthApi({
+      method: 'POST',
+      path: `/agent/surface/${surfaceName}/connect-action`,
+      body: {},
+    });
+
+    if (response.action.type === 'url') {
+      window.open(response.action.url, '_blank', 'noopener,noreferrer');
+    }
+  } finally {
+    connectingSurfaceName.value = null;
+  }
+}
+
+async function disconnectSurface(surfaceName: string) {
+  disconnectingSurfaceName.value = surfaceName;
+
+  try {
+    await callAdminForthApi({
+      method: 'POST',
+      path: `/agent/surface/${surfaceName}/disconnect`,
+      body: {},
+    });
+    await loadSurfaces();
+  } finally {
+    disconnectingSurfaceName.value = null;
+  }
+}
+
+function isSurfaceBusy(surfaceName: string) {
+  return connectingSurfaceName.value === surfaceName || disconnectingSurfaceName.value === surfaceName;
+}
+
+function formatSurfaceName(surfaceName: string) {
+  return surfaceName.charAt(0).toUpperCase() + surfaceName.slice(1);
+}
+</script>

package/custom/incremark_code_renderers/incremarkRenderer.ts

@@ -625,11 +625,11 @@ function sanitizeClassToken(value: string): string {
 
 function escapeHtml(value: string): string {
 	return value
-		.replaceAll('&', '&')
-		.replaceAll('<', '&lt;')
-		.replaceAll('>', '&gt;')
-		.replaceAll('"', '&quot;')
-		.replaceAll("'", '&#39;');
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;');
 }
 
 function escapeAttribute(value: string): string {

package/dist/custom/ChatSurfaceSettings.vue

@@ -0,0 +1,125 @@
+<template>
+  <div class="flex flex-col justify-center mr-6 md:mr-12">
+    <h2 class="flex items-start justify-start leading-none text-gray-800 dark:text-gray-50 text-3xl font-semibold">
+      {{ $t('Chat Surfaces') }}
+    </h2>
+    <p class="text-sm mt-3">
+      {{ $t('Connect external chat accounts to your AdminForth user') }}
+    </p>
+
+    <div class="mt-6 flex flex-wrap gap-4">
+      <div
+        v-for="surface in surfaces"
+        :key="surface.name"
+        class="flex flex-col w-full lg:w-72 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl p-4 shadow-sm"
+      >
+        <div class="flex items-center justify-between gap-3 mb-4">
+          <div class="min-w-0">
+            <p class="font-semibold text-gray-900 dark:text-white truncate">
+              {{ formatSurfaceName(surface.name) }}
+            </p>
+            <p class="text-xs text-gray-500 dark:text-gray-400">
+              {{ surface.externalUserId || $t('Not connected') }}
+            </p>
+          </div>
+          <span
+            class="shrink-0 inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium"
+            :class="surface.externalUserId
+              ? 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200'
+              : 'bg-gray-100 text-gray-700 dark:bg-gray-700 dark:text-gray-300'"
+          >
+            {{ surface.externalUserId ? $t('Active') : $t('Inactive') }}
+          </span>
+        </div>
+
+        <div class="grid gap-2 mt-auto" :class="surface.externalUserId ? 'grid-cols-2' : 'grid-cols-1'">
+          <Button
+            class="w-full"
+            :disabled="isSurfaceBusy(surface.name)"
+            :loader="connectingSurfaceName === surface.name"
+            @click="connectSurface(surface.name)"
+          >
+            {{ surface.externalUserId ? $t('Reconnect') : $t('Connect') }}
+          </Button>
+          <Button
+            v-if="surface.externalUserId"
+            class="w-full"
+            :disabled="isSurfaceBusy(surface.name)"
+            :loader="disconnectingSurfaceName === surface.name"
+            @click="disconnectSurface(surface.name)"
+          >
+            {{ $t('Disconnect') }}
+          </Button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { Button } from '@/afcl';
+import { callAdminForthApi } from '@/utils';
+
+type ChatSurface = {
+  name: string;
+  externalUserId: string | null;
+};
+
+const surfaces = ref<ChatSurface[]>([]);
+const connectingSurfaceName = ref<string | null>(null);
+const disconnectingSurfaceName = ref<string | null>(null);
+
+onMounted(loadSurfaces);
+
+async function loadSurfaces() {
+  const response = await callAdminForthApi({
+    method: 'POST',
+    path: '/agent/surfaces/connectable',
+    body: {},
+  });
+
+  surfaces.value = response.surfaces;
+}
+
+async function connectSurface(surfaceName: string) {
+  connectingSurfaceName.value = surfaceName;
+
+  try {
+    const response = await callAdminForthApi({
+      method: 'POST',
+      path: `/agent/surface/${surfaceName}/connect-action`,
+      body: {},
+    });
+
+    if (response.action.type === 'url') {
+      window.open(response.action.url, '_blank', 'noopener,noreferrer');
+    }
+  } finally {
+    connectingSurfaceName.value = null;
+  }
+}
+
+async function disconnectSurface(surfaceName: string) {
+  disconnectingSurfaceName.value = surfaceName;
+
+  try {
+    await callAdminForthApi({
+      method: 'POST',
+      path: `/agent/surface/${surfaceName}/disconnect`,
+      body: {},
+    });
+    await loadSurfaces();
+  } finally {
+    disconnectingSurfaceName.value = null;
+  }
+}
+
+function isSurfaceBusy(surfaceName: string) {
+  return connectingSurfaceName.value === surfaceName || disconnectingSurfaceName.value === surfaceName;
+}
+
+function formatSurfaceName(surfaceName: string) {
+  return surfaceName.charAt(0).toUpperCase() + surfaceName.slice(1);
+}
+</script>

package/dist/custom/incremark_code_renderers/incremarkRenderer.ts

@@ -625,11 +625,11 @@ function sanitizeClassToken(value: string): string {
 
 function escapeHtml(value: string): string {
 	return value
-		.replaceAll('&', '&')
-		.replaceAll('<', '&lt;')
-		.replaceAll('>', '&gt;')
-		.replaceAll('"', '&quot;')
-		.replaceAll("'", '&#39;');
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;');
 }
 
 function escapeAttribute(value: string): string {

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     options: PluginOptions;
     agentSystemPromptPromise: Promise<string>;
     private checkpointer;
+    private chatSurfaceLinkTokens;
+    private chatSurfaceSettingsPageRegistered;
     private parseBody;
     private createNewTurn;
     private getSessionTurns;
@@ -40,6 +42,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     private getOrCreateChatSurfaceSession;
     private getCheckpointer;
     private getInternalAgentResourceIds;
+    private getChatSurfaceConnectActionAdapters;
     constructor(options: PluginOptions);
     modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource): Promise<void>;
     validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource): void;
@@ -53,6 +56,9 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         failed: boolean;
     }>;
     private createChatSurfaceEventEmitter;
+    private createChatSurfaceLinkToken;
+    private consumeChatSurfaceLinkToken;
+    private handleChatSurfaceLink;
     private handleChatSurfaceMessage;
     setupEndpoints(server: IHttpServer): void;
 }

package/dist/index.js

@@ -50,6 +50,8 @@ const createSessionBodySchema = z.object({
 }).strict();
 const VEGA_LITE_FENCE_START = "```vega-lite";
 const COMPLETE_VEGA_LITE_BLOCK_RE = /```vega-lite[\s\S]*?```/;
+const DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD = "externalUserId";
+const CHAT_SURFACE_LINK_TOKEN_TTL_MS = 60 * 1000;
 function isAbortError(error) {
     return (error instanceof DOMException && error.name === "AbortError") || (typeof error === "object" &&
         error !== null &&
@@ -59,12 +61,6 @@ 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 : {});
@@ -141,9 +137,17 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             (_a = this.options.checkpointResource) === null || _a === void 0 ? void 0 : _a.resourceId,
         ].filter((resourceId) => Boolean(resourceId));
     }
+    getChatSurfaceConnectActionAdapters() {
+        var _a;
+        return ((_a = this.options.chatSurfaceAdapters) !== null && _a !== void 0 ? _a : [])
+            .map((adapter) => adapter)
+            .filter((adapter) => adapter.createConnectAction);
+    }
     constructor(options) {
         super(options, import.meta.url);
         this.checkpointer = null;
+        this.chatSurfaceLinkTokens = new Map();
+        this.chatSurfaceSettingsPageRegistered = false;
         this.options = options;
         this.agentSystemPromptPromise = Promise.resolve(appendCustomSystemPrompt(DEFAULT_AGENT_SYSTEM_PROMPT, this.options.systemPrompt));
         this.shouldHaveSingleInstancePerWholeApp = () => false;
@@ -171,6 +175,19 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     hasAudioAdapter: Boolean(this.options.audioAdapter),
                 }
             });
+            if (this.getChatSurfaceConnectActionAdapters().length && !this.chatSurfaceSettingsPageRegistered) {
+                if (!this.adminforth.config.auth.userMenuSettingsPages) {
+                    this.adminforth.config.auth.userMenuSettingsPages = [];
+                }
+                this.adminforth.config.auth.userMenuSettingsPages.push({
+                    icon: "flowbite:link-outline",
+                    pageLabel: "Chat Surfaces",
+                    slug: "chat-surfaces",
+                    component: this.componentPath("ChatSurfaceSettings.vue"),
+                    isVisible: () => true,
+                });
+                this.chatSurfaceSettingsPageRegistered = true;
+            }
             if (!this.adminforth.config.customization.customHeadItems) {
                 this.adminforth.config.customization.customHeadItems = [];
             }
@@ -485,25 +502,87 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             }
         });
     }
-    handleChatSurfaceMessage(adapter, incoming, sink) {
+    createChatSurfaceLinkToken(surface, adminUser) {
+        for (const [token, payload] of this.chatSurfaceLinkTokens) {
+            if (payload.expiresAt <= Date.now()) {
+                this.chatSurfaceLinkTokens.delete(token);
+            }
+        }
+        const token = randomUUID();
+        this.chatSurfaceLinkTokens.set(token, {
+            surface,
+            adminUserId: adminUser.pk,
+            expiresAt: Date.now() + CHAT_SURFACE_LINK_TOKEN_TTL_MS,
+        });
+        return token;
+    }
+    consumeChatSurfaceLinkToken(surface, token) {
+        const payload = this.chatSurfaceLinkTokens.get(token);
+        this.chatSurfaceLinkTokens.delete(token);
+        if (!payload || payload.surface !== surface || payload.expiresAt <= Date.now()) {
+            return null;
+        }
+        return payload;
+    }
+    handleChatSurfaceLink(incoming, sink) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            const adminUser = yield adapter.resolveAdminUser({
-                adminforth: this.adminforth,
-                incoming,
+            var _a, _b, _c;
+            if (typeof ((_a = incoming.metadata) === null || _a === void 0 ? void 0 : _a.startPayload) !== "string") {
+                return false;
+            }
+            const payload = this.consumeChatSurfaceLinkToken(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 externalUserIdField = (_b = this.options.chatExternalIdsField) !== null && _b !== void 0 ? _b : DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+            const authResourceId = this.adminforth.config.auth.usersResourceId;
+            const authResource = this.adminforth.config.resources.find((resource) => resource.resourceId === authResourceId);
+            const primaryKeyField = authResource.columns.find((column) => column.primaryKey).name;
+            const adminUserRecord = yield this.adminforth.resource(authResourceId).get([
+                Filters.EQ(primaryKeyField, payload.adminUserId),
+            ]);
+            yield this.adminforth.resource(authResourceId).update(payload.adminUserId, {
+                [externalUserIdField]: Object.assign(Object.assign({}, ((_c = adminUserRecord[externalUserIdField]) !== null && _c !== void 0 ? _c : {})), { [incoming.surface]: incoming.externalUserId }),
+            });
+            yield sink.emit({
+                type: "done",
+                text: `${incoming.surface} account connected to AdminForth.`,
             });
-            if (!adminUser) {
+            return true;
+        });
+    }
+    handleChatSurfaceMessage(adapter, incoming, sink) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            if (yield this.handleChatSurfaceLink(incoming, sink)) {
+                return;
+            }
+            const authResourceId = this.adminforth.config.auth.usersResourceId;
+            const authResource = this.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 this.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[this.adminforth.config.auth.usernameField],
+                dbUser: adminUserRecord,
+            };
             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",
+                userTimeZone: (_b = incoming.userTimeZone) !== null && _b !== void 0 ? _b : "UTC",
                 adminUser,
                 emit: this.createChatSurfaceEventEmitter(sink),
                 failureLogMessage: `Agent ${incoming.surface} surface response failed`,
@@ -513,7 +592,57 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     }
     setupEndpoints(server) {
         var _a;
+        if (this.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 = this.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: this.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 = this.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 = this.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 = this.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 this.adminforth.resource(this.adminforth.config.auth.usersResourceId).update(adminUser.pk, {
+                            [externalUserIdField]: externalIds,
+                        });
+                        return {
+                            ok: true,
+                        };
+                    }),
+                });
+            }
             server.endpoint({
                 method: "POST",
                 noAuth: true,
@@ -545,14 +674,13 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
             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: currentAdminUser,
+                    adminUser: adminUser,
                     headers,
                 });
                 return {
@@ -565,7 +693,6 @@ 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;
@@ -580,7 +707,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     userTimeZone: (_b = data.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
                     currentPage: data.currentPage,
                     abortSignal,
-                    adminUser: currentAdminUser,
+                    adminUser: adminUser,
                     emit,
                     failureLogMessage: "Agent response streaming failed",
                     abortLogMessage: "Agent response streaming aborted by the client",
@@ -594,7 +721,6 @@ 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) {
@@ -660,7 +786,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
                     userTimeZone: (_b = data.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
                     currentPage,
                     abortSignal,
-                    adminUser: currentAdminUser,
+                    adminUser: adminUser,
                     emit: (event) => __awaiter(this, void 0, void 0, function* () {
                         if (event.type === "tool-call") {
                             yield emit(event);
@@ -762,11 +888,10 @@ 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 = currentAdminUser.pk;
+                const userId = adminUser.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 {
@@ -782,13 +907,12 @@ 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 = currentAdminUser.pk;
+                const userId = adminUser.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) {
@@ -831,12 +955,11 @@ 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 = currentAdminUser.pk;
+                const userId = adminUser.pk;
                 const title = (triggerMessage === null || triggerMessage === void 0 ? void 0 : triggerMessage.slice(0, 40)) || "New Session";
                 const newSession = {
                     [this.options.sessionResource.idField]: randomUUID(),
@@ -856,12 +979,11 @@ 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 = currentAdminUser.pk;
+                const userId = adminUser.pk;
                 const session = yield this.adminforth.resource(this.options.sessionResource.resourceId).get([Filters.EQ(this.options.sessionResource.idField, sessionId)]);
                 if (!session) {
                     return {

package/dist/types.d.ts

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

package/index.ts

@@ -4,6 +4,7 @@ import type {
   ChatSurfaceAdapter,
   ChatSurfaceEventSink,
   ChatSurfaceIncomingMessage,
+  IAdminForthEndpointHandlerInput,
   IAdminForth,
   IHttpServer,
 } from "adminforth";
@@ -36,6 +37,24 @@ type MulterFile = {
 
 type ExpressMulterRequest = { file?: MulterFile };
 
+type ChatSurfaceConnectAction = {
+  type: "url";
+  label: string;
+  url: string;
+};
+
+type ChatSurfaceAdapterWithConnectAction = ChatSurfaceAdapter & {
+  createConnectAction?(input: {
+    token: string;
+  }): ChatSurfaceConnectAction | Promise<ChatSurfaceConnectAction>;
+};
+
+type ChatSurfaceLinkTokenPayload = {
+  surface: string;
+  adminUserId: AdminUser["pk"];
+  expiresAt: number;
+};
+
 type AgentTurnRunInput = {
   prompt: string;
   sessionId: string;
@@ -91,6 +110,8 @@ const createSessionBodySchema = z.object({
 
 const VEGA_LITE_FENCE_START = "```vega-lite";
 const COMPLETE_VEGA_LITE_BLOCK_RE = /```vega-lite[\s\S]*?```/;
+const DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD = "externalUserId";
+const CHAT_SURFACE_LINK_TOKEN_TTL_MS = 60 * 1000;
 
 function isAbortError(error: unknown): boolean {
   return (
@@ -107,18 +128,12 @@ function getErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function requireAdminUser(adminUser: AdminUser | undefined): AdminUser {
-  if (!adminUser) {
-    throw new Error("AdminForth Agent endpoint requires an authenticated admin user");
-  }
-
-  return adminUser;
-}
-
 export default class AdminForthAgentPlugin extends AdminForthPlugin {
   options: PluginOptions;
   agentSystemPromptPromise: Promise<string>;
   private checkpointer: BaseCheckpointSaver | null = null;
+  private chatSurfaceLinkTokens = new Map<string, ChatSurfaceLinkTokenPayload>();
+  private chatSurfaceSettingsPageRegistered = false;
   private parseBody<T>(
     schema: z.ZodType<T>,
     body: unknown,
@@ -215,6 +230,12 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     ].filter((resourceId): resourceId is string => Boolean(resourceId));
   }
 
+  private getChatSurfaceConnectActionAdapters() {
+    return (this.options.chatSurfaceAdapters ?? [])
+      .map((adapter) => adapter as ChatSurfaceAdapterWithConnectAction)
+      .filter((adapter) => adapter.createConnectAction);
+  }
+
   constructor(options: PluginOptions) {
     super(options, import.meta.url);
     this.options = options;
@@ -242,6 +263,19 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         hasAudioAdapter: Boolean(this.options.audioAdapter),
       }
     });
+    if (this.getChatSurfaceConnectActionAdapters().length && !this.chatSurfaceSettingsPageRegistered) {
+      if (!this.adminforth.config.auth!.userMenuSettingsPages) {
+        this.adminforth.config.auth!.userMenuSettingsPages = [];
+      }
+      this.adminforth.config.auth!.userMenuSettingsPages.push({
+        icon: "flowbite:link-outline",
+        pageLabel: "Chat Surfaces",
+        slug: "chat-surfaces",
+        component: this.componentPath("ChatSurfaceSettings.vue"),
+        isVisible: () => true,
+      });
+      this.chatSurfaceSettingsPageRegistered = true;
+    }
     if (!this.adminforth.config.customization.customHeadItems) {
       this.adminforth.config.customization.customHeadItems = [];
     }
@@ -576,17 +610,90 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     };
   }
 
+  private createChatSurfaceLinkToken(surface: string, adminUser: AdminUser) {
+    for (const [token, payload] of this.chatSurfaceLinkTokens) {
+      if (payload.expiresAt <= Date.now()) {
+        this.chatSurfaceLinkTokens.delete(token);
+      }
+    }
+
+    const token = randomUUID();
+    this.chatSurfaceLinkTokens.set(token, {
+      surface,
+      adminUserId: adminUser.pk,
+      expiresAt: Date.now() + CHAT_SURFACE_LINK_TOKEN_TTL_MS,
+    });
+
+    return token;
+  }
+
+  private consumeChatSurfaceLinkToken(surface: string, token: string) {
+    const payload = this.chatSurfaceLinkTokens.get(token);
+    this.chatSurfaceLinkTokens.delete(token);
+
+    if (!payload || payload.surface !== surface || payload.expiresAt <= Date.now()) {
+      return null;
+    }
+
+    return payload;
+  }
+
+  private async handleChatSurfaceLink(
+    incoming: ChatSurfaceIncomingMessage,
+    sink: ChatSurfaceEventSink,
+  ) {
+    if (typeof incoming.metadata?.startPayload !== "string") {
+      return false;
+    }
+
+    const payload = this.consumeChatSurfaceLinkToken(incoming.surface, incoming.metadata.startPayload);
+    if (!payload) {
+      await sink.emit({
+        type: "error",
+        message: "This chat surface link is expired or invalid. Please start linking again from AdminForth.",
+      });
+      return true;
+    }
+    const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+    const authResourceId = this.adminforth.config.auth!.usersResourceId!;
+    const authResource = this.adminforth.config.resources.find((resource) => resource.resourceId === authResourceId)!;
+    const primaryKeyField = authResource.columns.find((column) => column.primaryKey)!.name!;
+    const adminUserRecord = await this.adminforth.resource(authResourceId).get([
+      Filters.EQ(primaryKeyField, payload.adminUserId),
+    ]);
+
+    await this.adminforth.resource(authResourceId).update(payload.adminUserId, {
+      [externalUserIdField]: {
+        ...(adminUserRecord[externalUserIdField] ?? {}),
+        [incoming.surface]: incoming.externalUserId,
+      },
+    });
+    await sink.emit({
+      type: "done",
+      text: `${incoming.surface} account connected to AdminForth.`,
+    });
+
+    return true;
+  }
+
   private async handleChatSurfaceMessage(
     adapter: ChatSurfaceAdapter,
     incoming: ChatSurfaceIncomingMessage,
     sink: ChatSurfaceEventSink,
   ) {
-    const adminUser = await adapter.resolveAdminUser({
-      adminforth: this.adminforth,
-      incoming,
-    });
+    if (await this.handleChatSurfaceLink(incoming, sink)) {
+      return;
+    }
 
-    if (!adminUser) {
+    const authResourceId = this.adminforth.config.auth!.usersResourceId!;
+    const authResource = this.adminforth.config.resources.find((resource) => resource.resourceId === authResourceId)!;
+    const primaryKeyField = authResource.columns.find((column) => column.primaryKey)!.name!;
+    const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+    const adminUserRecord = (
+      await this.adminforth.resource(authResourceId).list(Filters.IS_NOT_EMPTY(externalUserIdField))
+    ).find((user) => user[externalUserIdField]?.[adapter.name] === incoming.externalUserId);
+
+    if (!adminUserRecord) {
       await sink.emit({
         type: "error",
         message: "This chat account is not authorized to use AdminForth Agent.",
@@ -594,6 +701,12 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       return;
     }
 
+    const adminUser = {
+      pk: adminUserRecord[primaryKeyField],
+      username: adminUserRecord[this.adminforth.config.auth!.usernameField],
+      dbUser: adminUserRecord,
+    };
+
     await this.handleTurn({
       prompt: incoming.prompt,
       sessionId: await this.getOrCreateChatSurfaceSession(incoming, adminUser),
@@ -607,12 +720,66 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
   }
 
   setupEndpoints(server: IHttpServer) {
+    if (this.getChatSurfaceConnectActionAdapters().length) {
+      server.endpoint({
+        method: "POST",
+        path: "/agent/surfaces/connectable",
+        handler: async ({ adminUser }) => {
+          const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+          const externalIds = adminUser.dbUser[externalUserIdField] ?? {};
+
+          return {
+            surfaces: this.getChatSurfaceConnectActionAdapters().map((adapter) => ({
+              name: adapter.name,
+              externalUserId: externalIds[adapter.name] ?? null,
+            })),
+          };
+        },
+      });
+    }
+
     for (const adapter of this.options.chatSurfaceAdapters ?? []) {
+      const connectActionAdapter = adapter as ChatSurfaceAdapterWithConnectAction;
+      if (connectActionAdapter.createConnectAction) {
+        server.endpoint({
+          method: "POST",
+          path: `/agent/surface/${adapter.name}/connect-action`,
+          handler: async ({ adminUser }) => {
+            const token = this.createChatSurfaceLinkToken(adapter.name, adminUser);
+            const action = await connectActionAdapter.createConnectAction!({ token });
+
+            return {
+              action,
+            };
+          },
+        });
+        server.endpoint({
+          method: "POST",
+          path: `/agent/surface/${adapter.name}/disconnect`,
+          handler: async ({ adminUser }) => {
+            const externalUserIdField = this.options.chatExternalIdsField ?? DEFAULT_ADMIN_USER_EXTERNAL_USER_ID_FIELD;
+            const externalIds = {
+              ...(adminUser.dbUser[externalUserIdField] ?? {}),
+            };
+
+            delete externalIds[adapter.name];
+
+            await this.adminforth.resource(this.adminforth.config.auth!.usersResourceId!).update(adminUser.pk, {
+              [externalUserIdField]: externalIds,
+            });
+
+            return {
+              ok: true,
+            };
+          },
+        });
+      }
+
       server.endpoint({
         method: "POST",
         noAuth: true,
         path: `/agent/surface/${adapter.name}/webhook`,
-        handler: async (ctx) => {
+        handler: async (ctx: IAdminForthEndpointHandlerInput) => {
           const surfaceContext = {
             body: ctx.body,
             headers: ctx.headers,
@@ -641,8 +808,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/get-placeholder-messages`,
       handler: async ({ headers, adminUser }) => {
-        const currentAdminUser = requireAdminUser(adminUser);
-
         if (!this.options.placeholderMessages) {
           return {
             messages: [],
@@ -650,7 +815,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
         }
 
         const messages = await this.options.placeholderMessages({
-          adminUser: currentAdminUser,
+          adminUser: adminUser,
           headers,
         });
 
@@ -663,7 +828,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/response`,
       handler: async ({ body, adminUser, response, _raw_express_res, abortSignal }) => {
-        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(agentResponseBodySchema, body, response);
         if (!data) return;
         const emit = createSseEventEmitter(_raw_express_res, {
@@ -678,7 +842,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
           userTimeZone: data.timeZone ?? 'UTC',
           currentPage: data.currentPage,
           abortSignal,
-          adminUser: currentAdminUser,
+          adminUser: adminUser,
           emit,
           failureLogMessage: "Agent response streaming failed",
           abortLogMessage: "Agent response streaming aborted by the client",
@@ -691,7 +855,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       path: `/agent/speech-response`,
       target: 'upload',
       handler: async ({ body, adminUser, response, _raw_express_req, _raw_express_res, abortSignal }) => {
-        const currentAdminUser = requireAdminUser(adminUser);
         const req = _raw_express_req as ExpressMulterRequest;
         const audioAdapter = this.options.audioAdapter;
         if (!audioAdapter) {
@@ -761,7 +924,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
           userTimeZone: data.timeZone ?? 'UTC',
           currentPage,
           abortSignal,
-          adminUser: currentAdminUser,
+          adminUser: adminUser,
           emit: async (event) => {
             if (event.type === "tool-call") {
               await emit(event);
@@ -871,10 +1034,9 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/get-sessions`,
       handler: async ({body, adminUser, response }) => {
-        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(getSessionsBodySchema, body, response);
         if (!data) return;
-        const userId = currentAdminUser.pk;
+        const userId = adminUser.pk;
         const limit = data.limit ?? 20;
         const sessions = await this.adminforth.resource(this.options.sessionResource.resourceId).list(
           [Filters.EQ(this.options.sessionResource.askerIdField, userId)], limit, undefined, [Sorts.DESC(this.options.sessionResource.createdAtField)]
@@ -892,13 +1054,12 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/get-session-info`,
       handler: async ({body, adminUser, response }) => {
-        const currentAdminUser = requireAdminUser(adminUser);
         const parsedBody = sessionIdBodySchema.safeParse(body);
         if (!parsedBody.success) {
           response.setStatus(422, parsedBody.error.message);
           return;
         }
-        const userId = currentAdminUser.pk;
+        const userId = adminUser.pk;
         const sessionId = parsedBody.data.sessionId;
         const session = await this.adminforth.resource(this.options.sessionResource.resourceId).get(
           [Filters.EQ(this.options.sessionResource.idField, sessionId)]
@@ -943,11 +1104,10 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/create-session`,
       handler: async ({body, adminUser, response }) => {
-        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(createSessionBodySchema, body, response);
         if (!data) return;
         const triggerMessage = data.triggerMessage;
-        const userId = currentAdminUser.pk;
+        const userId = adminUser.pk;
         const title = triggerMessage?.slice(0, 40) || "New Session";
         const newSession = {
           [this.options.sessionResource.idField]: randomUUID(),
@@ -967,11 +1127,10 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       method: 'POST',
       path: `/agent/delete-session`,
       handler: async ({body, adminUser, response }) => {
-        const currentAdminUser = requireAdminUser(adminUser);
         const data = this.parseBody(sessionIdBodySchema, body, response);
         if (!data) return;
         const sessionId = data.sessionId;
-        const userId = currentAdminUser.pk;
+        const userId = adminUser.pk;
         const session = await this.adminforth.resource(this.options.sessionResource.resourceId).get(
           [Filters.EQ(this.options.sessionResource.idField, sessionId)]
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/agent",
-  "version": "1.44.2",
+  "version": "1.45.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "@langchain/core": "^1.1.40",
     "@langchain/langgraph": "^1.2.8",
     "@langchain/langgraph-checkpoint": "^1.0.1",
-    "adminforth": ">=2.54.0",
+    "adminforth": "^2.60.0",
     "dayjs": "^1.11.20",
     "langchain": "^1.3.3",
     "multer": "^2.1.1",

package/types.ts

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