@adminforth/agent 1.0.0

package/index.ts

@@ -0,0 +1,457 @@
+import type {
+  AdminForthResource,
+  AdminUser,
+  IAdminForth,
+  IHttpServer
+} from "adminforth";
+
+import { AdminForthPlugin, logger, Filters, Sorts } from "adminforth";
+
+import type { PluginOptions } from './types.js';
+import { randomUUID } from 'crypto';
+import { HumanMessage, SystemMessage } from "langchain";
+import { createAgentChatModel, callAgent } from "./agent/simpleAgent.js";
+import { createSequenceDebugCollector } from "./agent/middleware/sequenceDebug.js";
+import {
+  prepareApiBasedTools as buildApiBasedTools,
+} from './apiBasedTools.js';
+import type { ApiBasedTool } from './apiBasedTools.js';
+import {
+  buildAgentSystemPrompt,
+  DEFAULT_AGENT_SYSTEM_PROMPT,
+} from "./agent/systemPrompt.js";
+import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "./agent/tools/index.js";
+import type { ToolCallEvent } from "./agent/toolCallEvents.js";
+
+function isAggregateErrorLike(
+  error: unknown,
+): error is { errors: unknown[]; message?: string; stack?: string } {
+  return typeof error === "object" && error !== null && Array.isArray((error as { errors?: unknown[] }).errors);
+}
+
+function formatAgentError(error: unknown) {
+  if (isAggregateErrorLike(error)) {
+    const nestedErrors = error.errors
+      .map((nestedError, index) => {
+        if (nestedError instanceof Error) {
+          return `${index + 1}. ${nestedError.stack ?? nestedError.message}`;
+        }
+
+        return `${index + 1}. ${String(nestedError)}`;
+      })
+      .join("\n");
+
+    return `${error.stack ?? error.message}\nNested errors:\n${nestedErrors}`;
+  }
+
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+
+  return String(error);
+}
+
+function assertRequiredApiTool(
+  apiBasedTools: Record<string, ApiBasedTool>,
+  toolName: string,
+) {
+  if (toolName in apiBasedTools) {
+    return;
+  }
+
+  const availableToolNames = Object.keys(apiBasedTools).sort().join(", ");
+  throw new Error(
+    `Required API tool "${toolName}" is missing from AdminForth Agent tools. Available tools: ${availableToolNames}`,
+  );
+}
+
+export default class AdminForthAgentPlugin extends AdminForthPlugin {
+  options: PluginOptions;
+  apiBasedTools: Record<string, ApiBasedTool> = {};
+  agentSystemPromptPromise = Promise.resolve(DEFAULT_AGENT_SYSTEM_PROMPT);
+
+  private async createNewTurn(sessionId: string, prompt: string, response?: string) {
+    const turnId = randomUUID();
+    const turnRecord = {
+      [this.options.turnResource.idField]: turnId,
+      [this.options.turnResource.sessionIdField]: sessionId,
+      [this.options.turnResource.promptField]: prompt,
+      [this.options.turnResource.responseField]: response || "not_finished",
+    };
+    const newTurn = await this.adminforth.resource(this.options.turnResource.resourceId).create(turnRecord);
+    return newTurn.createdRecord[this.options.turnResource.idField];
+  }
+
+  private async updateTurn(turnId: string, updates: Record<string, unknown>) {
+    await this.adminforth.resource(this.options.turnResource.resourceId).update(turnId, updates);
+    return {ok: true};
+  }
+
+  private async getSessionTurns(sessionId: string) {
+    const turns = await this.adminforth.resource(this.options.turnResource.resourceId).list(
+      [Filters.EQ(this.options.turnResource.sessionIdField, sessionId)],
+      undefined,
+      undefined,
+      [Sorts.ASC(this.options.turnResource.createdAtField)]
+    );
+    return turns.map(turn => ({
+      prompt: turn[this.options.turnResource.promptField],
+      response: turn[this.options.turnResource.responseField],
+    }));
+  }
+
+  constructor(options: PluginOptions) {
+    super(options, import.meta.url);
+    this.options = options;
+    this.shouldHaveSingleInstancePerWholeApp = () => false;
+  }
+
+  async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
+    super.modifyResourceConfig(adminforth, resourceConfig);
+    if (!this.adminforth.config.customization.globalInjections.header) {
+      this.adminforth.config.customization.globalInjections.header = [];
+    }
+    this.adminforth.config.customization.globalInjections.header.push({
+      file: this.componentPath("ChatSurface.vue"),
+      meta: {
+        pluginInstanceId: this.pluginInstanceId,
+      }
+    });
+
+    if (!this.pluginOptions.completionAdapter) {
+      throw new Error("CompletionAdapter is required for AdminForthAgentPlugin");
+    }
+    if (!this.pluginOptions.sessionResource) {
+      throw new Error("sessionResource is required for AdminForthAgentPlugin");
+    }
+  }
+  
+  validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
+    this.apiBasedTools = buildApiBasedTools(adminforth);
+    for (const toolName of ALWAYS_AVAILABLE_API_TOOL_NAMES) {
+      assertRequiredApiTool(this.apiBasedTools, toolName);
+    }
+    assertRequiredApiTool(this.apiBasedTools, "update_record");
+    this.agentSystemPromptPromise = buildAgentSystemPrompt(adminforth);
+  }
+
+  instanceUniqueRepresentation(pluginOptions: any) : string {
+    return `single`;
+  }
+
+  setupEndpoints(server: IHttpServer) {
+    server.endpoint({
+      method: 'POST',
+      path: `/agent/response`,
+      handler: async ({ body, adminUser, _raw_express_res }) => {
+        const res = _raw_express_res;
+        const messageId = randomUUID();
+        const prompt = body.message;
+        const userTimeZone = (body.timeZone as string | undefined) ?? 'UTC';
+        const sessionId = body.sessionId || adminUser?.pk || adminUser?.username || 'default';
+        const turnId = await this.createNewTurn(sessionId, prompt);
+        let fullResponse = "";
+        let isStreamClosed = false;
+        const sequenceDebugCollector = createSequenceDebugCollector();
+
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          'Connection': 'keep-alive',
+          'x-vercel-ai-ui-message-stream': 'v1',
+        });
+
+        const send = (obj: unknown) => {
+          if (isStreamClosed || res.writableEnded || res.destroyed) {
+            return;
+          }
+          res.write(`data: ${JSON.stringify(obj)}\n\n`);
+        };
+
+        const emitToolCallEvent = (event: ToolCallEvent) => {
+          sequenceDebugCollector.handleToolCallEvent(event);
+
+          send({
+            type: "data-tool-call",
+            data: event,
+          });
+        };
+
+        let activeBlock: { type: 'text' | 'reasoning'; id: string } | null = null;
+
+        const endActiveBlock = () => {
+          if (!activeBlock) {
+            return;
+          }
+
+          send({
+            type: `${activeBlock.type}-end`,
+            id: activeBlock.id,
+          });
+
+          activeBlock = null;
+        };
+
+        const startBlock = (type: 'text' | 'reasoning') => {
+          if (activeBlock?.type === type) {
+            return activeBlock.id;
+          }
+
+          endActiveBlock();
+
+          const id = randomUUID();
+          activeBlock = { type, id };
+
+          send({
+            type: `${type}-start`,
+            id,
+          });
+
+          return id;
+        };
+
+        const endStream = () => {
+          if (isStreamClosed || res.writableEnded || res.destroyed) {
+            return;
+          }
+          endActiveBlock();
+
+          send({
+            type: 'finish',
+          });
+
+          res.write(`data: [DONE]\n\n`);
+          isStreamClosed = true;
+          res.end();
+        }
+
+        try {
+          send({
+            type: 'start',
+            messageId,
+          });
+
+          const maxTokens = this.options.maxTokens ?? 10000;
+          const reasoning = this.options.reasoning ?? 'low';
+          const summaryReasoning = 'low';
+
+          const model = createAgentChatModel({
+            adapter: this.options.completionAdapter,
+            maxTokens,
+            reasoning,
+          });
+
+          const summaryModel = createAgentChatModel({
+            adapter: this.options.completionAdapter,
+            maxTokens,
+            reasoning: summaryReasoning,
+          });
+          const systemPrompt = await this.agentSystemPromptPromise;
+          const stream = await callAgent({
+            name: `adminforth-agent-${this.pluginInstanceId}`,
+            model,
+            summaryModel,
+            messages: [
+              new SystemMessage(systemPrompt),
+              new HumanMessage(prompt),
+            ],
+            adminUser,
+            apiBasedTools: this.apiBasedTools,
+            customComponentsDir: this.adminforth.config.customization.customComponentsDir,
+            sessionId,
+            turnId,
+            userTimeZone,
+            emitToolCallEvent,
+            sequenceDebugSink: sequenceDebugCollector,
+          });
+
+          for await (const rawChunk of stream as AsyncIterable<[any, any]>) {
+            const [token, metadata] = rawChunk;
+
+            const nodeName =
+              typeof metadata?.langgraph_node === "string"
+                ? metadata.langgraph_node
+                : "";
+
+            if (nodeName && !["model", "model_request"].includes(nodeName)) {
+              continue;
+            }
+
+            const blocks = Array.isArray(token?.contentBlocks)
+              ? token.contentBlocks
+              : Array.isArray(token?.content)
+                ? token.content
+                : [];
+
+            const reasoningDelta = blocks
+              .filter((b: any) => b?.type === "reasoning")
+              .map((b: any) => String(b.reasoning ?? ""))
+              .join("");
+
+            const textDelta = blocks
+              .filter((b: any) => b?.type === "text")
+              .map((b: any) => String(b.text ?? ""))
+              .join("");
+
+            if (reasoningDelta) {
+              const reasoningId = startBlock('reasoning');
+                send({
+                  type: 'reasoning-delta',
+                  id: reasoningId,
+                  delta: reasoningDelta,
+                });
+            }
+
+            if (textDelta) {
+              const textId = startBlock('text');
+              fullResponse += textDelta;
+              send({
+                type: 'text-delta',
+                id: textId,
+                delta: textDelta,
+              });
+            }
+          }
+        } catch (error) {
+          logger.error(`Agent response streaming failed:\n${formatAgentError(error)}`);
+          sequenceDebugCollector.flush();
+          const textId = startBlock('text');
+          send({
+            type: 'text-delta',
+            id: textId,
+            delta: 'Agent response failed. Check server logs for details.',
+          });
+        }
+        sequenceDebugCollector.flush();
+        const turnUpdates: Record<string, unknown> = {
+          [this.options.turnResource.responseField]: fullResponse,
+        };
+
+        if (this.options.turnResource.debugField) {
+          turnUpdates[this.options.turnResource.debugField] = sequenceDebugCollector.getHistory();
+        }
+
+        await this.updateTurn(turnId, turnUpdates);
+        endStream();
+        return null;
+      }
+    });
+    server.endpoint({
+      method: 'POST',
+      path: `/agent/get-sessions`,
+      handler: async ({body, adminUser }) => {
+        const userId = adminUser.pk;
+        const sessions = await this.adminforth.resource(this.pluginOptions.sessionResource.resourceId).list(
+          [Filters.EQ(this.pluginOptions.sessionResource.askerIdField, userId)], undefined, undefined, [Sorts.DESC(this.pluginOptions.sessionResource.createdAtField)]
+        );
+        const sessionsToReturn = [];
+        for (const session of sessions) {
+         sessionsToReturn.push({
+          sessionId: session[this.pluginOptions.sessionResource.idField],
+          title: session[this.pluginOptions.sessionResource.titleField],
+          timestamp: session[this.pluginOptions.sessionResource.createdAtField],
+         })
+        }
+        return {
+          sessions: sessionsToReturn
+        };
+      }
+    });
+    server.endpoint({
+      method: 'POST',
+      path: `/agent/get-session-info`,
+      handler: async ({body, adminUser }) => {
+        const userId = adminUser.pk;
+        const sessionId = body.sessionId;
+        const session = await this.adminforth.resource(this.pluginOptions.sessionResource.resourceId).get(
+          [Filters.EQ(this.pluginOptions.sessionResource.idField, sessionId)]
+        );
+        if (!session) {
+          return {
+            error: 'Session not found'
+          };
+        }
+        if (session[this.pluginOptions.sessionResource.askerIdField] !== userId) {
+          return {
+            error: 'Unauthorized'
+          };
+        }
+        const turns = await this.getSessionTurns(sessionId);
+        const messagesToReturn = [];
+        for (const turn of turns) {
+          messagesToReturn.push({
+            text: turn.prompt,
+            role: 'user',
+          });
+          if (turn.response !== "not_finished") {
+            messagesToReturn.push({
+              text: turn.response,
+              role: 'assistant',
+            });
+          }
+        }
+        const sessionToReturn = {
+          sessionId: session[this.pluginOptions.sessionResource.idField],
+          title: session[this.pluginOptions.sessionResource.titleField],
+          timestamp: session[this.pluginOptions.sessionResource.createdAtField],
+          messages: messagesToReturn
+        }
+        return {
+          session: sessionToReturn
+        }
+      }
+    });
+    server.endpoint({
+      method: 'POST',
+      path: `/agent/create-session`,
+      handler: async ({body, adminUser }) => {
+        const triggerMessage = body.triggerMessage;
+        const userId = adminUser.pk;
+        const title = triggerMessage ? (triggerMessage.length > 40 ? triggerMessage.slice(0, 40) + '...' : triggerMessage) : 'New Session';
+        const newSession = {
+          [this.pluginOptions.sessionResource.idField]: randomUUID(),
+          [this.pluginOptions.sessionResource.titleField]: title,
+          [this.pluginOptions.sessionResource.askerIdField]: userId,
+        };
+        await this.adminforth.resource(this.pluginOptions.sessionResource.resourceId).create(newSession);
+        return {
+          sessionId: newSession[this.pluginOptions.sessionResource.idField],
+          title: newSession[this.pluginOptions.sessionResource.titleField],
+          timestamp: newSession[this.pluginOptions.sessionResource.createdAtField],
+          messages: []
+        };
+      }
+    });
+    server.endpoint({
+      method: 'POST',
+      path: `/agent/delete-session`,
+      handler: async ({body, adminUser }) => {
+        const sessionId = body.sessionId;
+        const userId = adminUser.pk;
+        const session = await this.adminforth.resource(this.pluginOptions.sessionResource.resourceId).get(
+          [Filters.EQ(this.pluginOptions.sessionResource.idField, sessionId)]
+        );
+        if (!session) {
+          return {
+            error: 'Session not found'
+          };
+        }
+        if (session[this.pluginOptions.sessionResource.askerIdField] !== userId) {
+          return {
+            error: 'Unauthorized'
+          };
+        }
+        await this.adminforth.resource(this.pluginOptions.sessionResource.resourceId).delete(sessionId);
+        const turns = await this.adminforth.resource(this.pluginOptions.turnResource.resourceId).list(
+          [Filters.EQ(this.pluginOptions.turnResource.sessionIdField, sessionId)]
+        );
+        for (const turn of turns) {
+          await this.adminforth.resource(this.pluginOptions.turnResource.resourceId).delete(turn[this.pluginOptions.turnResource.idField]);
+        }
+        return {
+          ok: true
+        };
+      }
+    });
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@adminforth/agent",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && rsync -av --exclude 'node_modules' custom dist/"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "latest",
+    "semantic-release": "^24.2.1",
+    "semantic-release-slack-bot": "^4.0.2",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.1.40",
+    "@langchain/langgraph": "^1.2.8",
+    "@langchain/openai": "^1.4.4",
+    "adminforth": "2.27.0-next.47",
+    "dayjs": "^1.11.20",
+    "langchain": "^1.3.3",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "release": {
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "semantic-release-slack-bot",
+        {
+          "packageName": "@adminforth/agent",
+          "notifyOnSuccess": true,
+          "notifyOnFail": true,
+          "slackIcon": ":package:",
+          "markdownReleaseNotes": true
+        }
+      ]
+    ]
+  },
+  "branches": [
+    "main",
+    {
+      "name": "next",
+      "prerelease": true
+    }
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "compilerOptions": {
+      "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include*/ 
+      "module": "node16",                                /* Specify what module code is generated. */
+      "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
+      "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules.  */
+      "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+      "strict": false,                                     /* Enable all strict type-checking options. */
+      "skipLibCheck": true,                                 /* Skip type checking all .d.ts files. */
+    },
+    "exclude": ["node_modules", "dist", "custom"],           /* Exclude files from compilation. */
+  }
+  

package/types.ts

@@ -0,0 +1,45 @@
+import  {type PluginsCommonOptions } from "adminforth";
+import { type CompletionAdapter } from "adminforth";
+
+interface ISessionResource {
+  resourceId: string;
+  idField: string;
+  titleField: string;
+  turnsField: string;
+  askerIdField: string;
+  createdAtField: string;
+}
+
+interface ITurnResource {
+  resourceId: string;
+  idField: string;
+  sessionIdField: string;
+  createdAtField: string;
+  promptField: string;
+  responseField: string;
+  debugField?: string;
+}
+
+export interface PluginOptions extends PluginsCommonOptions {
+  /**
+   * Adapter instance that will be used to generate responses. 
+   * You can use any adapter that implements the CompletionAdapter interface, for example the OpenAIAdapter included in adminforth, 
+   * or create your own that fetches responses from your custom backend.
+   */
+  completionAdapter: CompletionAdapter;
+
+  /**
+   * Max tokens for the generation.
+   * Default is 1000
+   */
+  maxTokens?: number;
+
+  /**
+   * Response generation level.
+   * Default is low
+   */
+  reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+  sessionResource: ISessionResource;
+  turnResource: ITurnResource;
+}