@adminforth/agent 2.0.9 → 2.1.0

package/endpoints/core.ts

@@ -1,181 +0,0 @@
-import type { IHttpServer } from "adminforth";
-import { z } from "zod";
-import { createSseEventEmitter } from "../surfaces/web-sse/createSseEventEmitter.js";
-import type { CurrentPageContext } from "../agent/tools/getUserLocation.js";
-import type { CoreEndpointsContext } from "./context.js";
-
-type MulterFile = {
-  buffer: Buffer;
-  originalname: string;
-  mimetype: string;
-};
-
-type ExpressMulterRequest = { file?: MulterFile };
-
-const currentPageContextSchema = z.object({
-  path: z.string(),
-  fullPath: z.string(),
-  title: z.string(),
-  url: z.string(),
-}).strict() satisfies z.ZodType<CurrentPageContext>;
-
-const agentResponseBodySchema = z.object({
-  message: z.string(),
-  sessionId: z.string(),
-  mode: z.string().nullish(),
-  timeZone: z.string().optional(),
-  currentPage: currentPageContextSchema.optional(),
-}).strict();
-
-const agentApprovalBodySchema = z.object({
-  sessionId: z.string(),
-  decision: z.enum(["approve", "reject"]),
-}).strict();
-
-// Sent as multipart/form-data (via multer), so every field arrives as a plain string on the wire.
-// `currentPage` is JSON.stringify'd by the client into a form field and must be parsed back into
-// an object. Zod -> JSON-Schema conversion cannot represent `.transform()` at all (it throws), so
-// `agentSpeechResponseShapeSchema` (plain strings, no transform) is what's passed as request_schema
-// for the AJV pre-check, while `agentSpeechResponseBodySchema` (with the transform) is used via an
-// inline safeParse in the handler to actually parse `currentPage` into an object.
-const agentSpeechResponseShapeSchema = z.object({
-  sessionId: z.string(),
-  mode: z.string().nullish(),
-  timeZone: z.string().optional(),
-  currentPage: z.string().optional(),
-}).strict();
-
-const agentSpeechResponseBodySchema = agentSpeechResponseShapeSchema.extend({
-  currentPage: z.string().optional().transform((value, ctx) => {
-    if (value === undefined) return undefined;
-    try {
-      return currentPageContextSchema.parse(JSON.parse(value));
-    } catch (err) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `currentPage must be a JSON-encoded object matching CurrentPageContext: ${err instanceof Error ? err.message : String(err)}`,
-      });
-      return z.NEVER;
-    }
-  }),
-});
-
-export function setupCoreEndpoints(ctx: CoreEndpointsContext, server: IHttpServer) {
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/get-placeholder-messages`,
-    handler: async ({ headers, adminUser }) => {
-      if (!ctx.options.placeholderMessages) {
-        return {
-          messages: [],
-        };
-      }
-
-      const messages = await ctx.options.placeholderMessages({
-        adminUser: adminUser!,
-        headers,
-      });
-
-      return {
-        messages,
-      };
-    }
-  });
-
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/response`,
-    request_schema: agentResponseBodySchema,
-    handler: async ({ body, adminUser, response, _raw_express_res, abortSignal }) => {
-      const data = body as z.infer<typeof agentResponseBodySchema>;
-      const emit = createSseEventEmitter(_raw_express_res, {
-        vercelAiUiMessageStream: true,
-        closeActiveBlockOnToolStart: true,
-      });
-
-      await ctx.handleTurn({
-        prompt: data.message,
-        sessionId: data.sessionId,
-        modeName: data.mode,
-        userTimeZone: data.timeZone ?? 'UTC',
-        currentPage: data.currentPage,
-        abortSignal,
-        adminUser: adminUser!,
-        emit,
-        failureLogMessage: "Agent response streaming failed",
-        abortLogMessage: "Agent response streaming aborted by the client",
-      });
-      return null;
-    }
-  });
-
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/approval`,
-    request_schema: agentApprovalBodySchema,
-    handler: async ({ body, adminUser, response, _raw_express_res, abortSignal }) => {
-      const data = body as z.infer<typeof agentApprovalBodySchema>;
-      const emit = createSseEventEmitter(_raw_express_res, {
-        vercelAiUiMessageStream: true,
-        closeActiveBlockOnToolStart: true,
-      });
-
-      await ctx.handleTurn({
-        prompt: "",
-        sessionId: data.sessionId,
-        approvalDecision: data.decision,
-        abortSignal,
-        adminUser: adminUser!,
-        emit,
-        failureLogMessage: "Agent approval response streaming failed",
-        abortLogMessage: "Agent approval response streaming aborted by the client",
-      });
-      return null;
-    }
-  });
-
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/speech-response`,
-    target: 'upload',
-    request_schema: agentSpeechResponseShapeSchema,
-    handler: async ({ body, adminUser, response, _raw_express_req, _raw_express_res, abortSignal }) => {
-      const req = _raw_express_req as ExpressMulterRequest;
-      const audioAdapter = ctx.options.audioAdapter;
-      if (!audioAdapter) {
-        response.setStatus(400, "Audio adapter is not configured for AdminForth Agent");
-        return { error: "Audio adapter is not configured for AdminForth Agent" };
-      }
-      const parsed = agentSpeechResponseBodySchema.safeParse(body);
-      if (!parsed.success) {
-        response.setStatus(400, 'Request body validation failed');
-        return { error: 'Request body validation failed', details: parsed.error.issues };
-      }
-      const data = parsed.data;
-      if (!req.file) {
-        response.setStatus(400, "Audio file is required");
-        return { error: "Audio file is required" };
-      }
-      const emit = createSseEventEmitter(_raw_express_res);
-
-      await ctx.handleSpeechTurn({
-        audioAdapter,
-        audio: {
-          buffer: req.file.buffer,
-          filename: req.file.originalname,
-          mimeType: req.file.mimetype,
-        },
-        sessionId: data.sessionId,
-        modeName: data.mode,
-        userTimeZone: data.timeZone ?? 'UTC',
-        currentPage: data.currentPage,
-        abortSignal,
-        adminUser: adminUser!,
-        emit,
-        failureLogMessage: "Agent speech response failed",
-        abortLogMessage: "Agent speech response aborted by the client",
-      });
-      return null;
-    }
-  });
-}

package/endpoints/sessions.ts

@@ -1,183 +0,0 @@
-import type { IHttpServer } from "adminforth";
-import { Filters, Sorts } from "adminforth";
-import { randomUUID } from "crypto";
-import { z } from "zod";
-import { AGENT_SYSTEM_TURN_PROMPT } from "../sessionStore.js";
-import type { SessionEndpointsContext } from "./context.js";
-
-const addSystemMessageBodySchema = z.object({
-  sessionId: z.string(),
-  systemMessage: z.string(),
-}).strict();
-
-const getSessionsBodySchema = z.object({
-  limit: z.number().int().min(1).max(100).optional(),
-}).strict();
-
-const sessionIdBodySchema = z.object({
-  sessionId: z.string(),
-}).strict();
-
-const createSessionBodySchema = z.object({
-  triggerMessage: z.string().optional(),
-}).strict();
-
-export function setupSessionEndpoints(ctx: SessionEndpointsContext, server: IHttpServer) {
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/get-sessions`,
-    request_schema: getSessionsBodySchema,
-    handler: async ({body, adminUser, response }) => {
-      const data = body as z.infer<typeof getSessionsBodySchema>;
-      const userId = adminUser!.pk;
-      const limit = data.limit ?? 20;
-      const sessions = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).list(
-        [Filters.EQ(ctx.options.sessionResource.askerIdField, userId)], limit, undefined, [Sorts.DESC(ctx.options.sessionResource.createdAtField)]
-      );
-      return {
-        sessions: sessions.map((session) => ({
-          sessionId: session[ctx.options.sessionResource.idField],
-          title: session[ctx.options.sessionResource.titleField],
-          timestamp: session[ctx.options.sessionResource.createdAtField],
-        })),
-      };
-    }
-  });
-
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/get-session-info`,
-    request_schema: sessionIdBodySchema,
-    handler: async ({body, adminUser, response }) => {
-      const data = body as z.infer<typeof sessionIdBodySchema>;
-      const userId = adminUser!.pk;
-      const sessionId = data.sessionId;
-      const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
-        [Filters.EQ(ctx.options.sessionResource.idField, sessionId)]
-      );
-      if (!session) {
-        return {
-          error: 'Session not found'
-        };
-      }
-      if (session[ctx.options.sessionResource.askerIdField] !== userId) {
-        return {
-          error: 'Unauthorized'
-        };
-      }
-      const turns = await ctx.getSessionTurns(sessionId);
-      return {
-        session: {
-          sessionId,
-          title: session[ctx.options.sessionResource.titleField],
-          timestamp: session[ctx.options.sessionResource.createdAtField],
-          messages: turns.flatMap(turn => {
-            const messages: Array<{ text: string; role: 'user' | 'assistant' | 'system' }> = [];
-            if (turn.prompt === AGENT_SYSTEM_TURN_PROMPT) {
-              messages.push({
-                text: turn.response,
-                role: 'system',
-              });
-              return messages;
-            }
-            if (turn.prompt) {
-              messages.push({
-                text: turn.prompt,
-                role: 'user',
-              });
-            }
-            if (turn.response && turn.response !== "not_finished") {
-              messages.push({
-                text: turn.response,
-                role: 'assistant',
-              });
-            }
-            return messages;
-          }),
-        },
-      };
-    }
-  });
-
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/create-session`,
-    request_schema: createSessionBodySchema,
-    handler: async ({body, adminUser, response }) => {
-      const data = body as z.infer<typeof createSessionBodySchema>;
-      const triggerMessage = data.triggerMessage;
-      const userId = adminUser!.pk;
-      const title = triggerMessage?.slice(0, 40) || "New Session";
-      const newSession = {
-        [ctx.options.sessionResource.idField]: randomUUID(),
-        [ctx.options.sessionResource.titleField]: title,
-        [ctx.options.sessionResource.askerIdField]: userId,
-      };
-      const { createdRecord } = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).create(newSession);
-      return {
-        sessionId: createdRecord[ctx.options.sessionResource.idField],
-        title: createdRecord[ctx.options.sessionResource.titleField],
-        timestamp: createdRecord[ctx.options.sessionResource.createdAtField],
-        messages: []
-      };
-    }
-  });
-
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/delete-session`,
-    request_schema: sessionIdBodySchema,
-    handler: async ({body, adminUser, response }) => {
-      const data = body as z.infer<typeof sessionIdBodySchema>;
-      const sessionId = data.sessionId;
-      const userId = adminUser!.pk;
-      const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
-        [Filters.EQ(ctx.options.sessionResource.idField, sessionId)]
-      );
-      if (!session) {
-        return {
-          error: 'Session not found'
-        };
-      }
-      if (session[ctx.options.sessionResource.askerIdField] !== userId) {
-        return {
-          error: 'Unauthorized'
-        };
-      }
-      await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).delete(sessionId);
-      const turns = await ctx.adminforth.resource(ctx.options.turnResource.resourceId).list(
-        [Filters.EQ(ctx.options.turnResource.sessionIdField, sessionId)]
-      );
-      await Promise.all(turns.map(turn => ctx.adminforth.resource(ctx.options.turnResource.resourceId).delete(turn[ctx.options.turnResource.idField])));
-      return {
-        ok: true
-      };
-    }
-  });
-
-  server.endpoint({
-    method: 'POST',
-    path: `/agent/add-system-message-to-turns`,
-    request_schema: addSystemMessageBodySchema,
-    handler: async ({body, adminUser, response }) => {
-      const data = body as z.infer<typeof addSystemMessageBodySchema>;
-      const session = await ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get(
-        [Filters.EQ(ctx.options.sessionResource.idField, data.sessionId)]
-      );
-      if (!session) {
-        return {
-          error: 'Session not found'
-        };
-      }
-      if (session[ctx.options.sessionResource.askerIdField] !== adminUser!.pk) {
-        return {
-          error: 'Unauthorized'
-        };
-      }
-      await ctx.createSystemTurn(data.sessionId, data.systemMessage);
-      return {
-        ok: true
-      }
-    }
-  })
-}

package/errors.ts

@@ -1,10 +0,0 @@
-export function isAbortError(error: unknown): boolean {
-  return typeof error === "object" &&
-    error !== null &&
-    "name" in error &&
-    (error.name === "AbortError" || error.name === "APIUserAbortError");
-}
-
-export function getErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/index.ts

@@ -1,192 +0,0 @@
-import type {
-  AdminForthResource,
-  IAdminForth,
-  IHttpServer,
-} from "adminforth";
-
-import { AdminForthPlugin } from "adminforth";
-
-import type { PluginOptions } from './types.js';
-import { MemorySaver, type BaseCheckpointSaver } from "@langchain/langgraph";
-import { AdminForthCheckpointSaver } from "./agent/checkpointer.js";
-import { appendCustomSystemPrompt, buildAgentSystemPrompt, DEFAULT_AGENT_SYSTEM_PROMPT} from "./agent/systemPrompt.js";
-import { setupCoreEndpoints } from "./endpoints/core.js";
-import { setupSessionEndpoints } from "./endpoints/sessions.js";
-import { setupChatSurfaceEndpoints } from "./endpoints/chatSurfaces.js";
-import type { AgentEndpointsContext } from "./endpoints/context.js";
-import { AgentSessionStore } from "./sessionStore.js";
-import { ChatSurfaceService } from "./chatSurfaceService.js";
-import { AgentTurnService } from "./agentTurnService.js";
-import { AgentModelFactory } from "./agent/models/AgentModelFactory.js";
-import { AgentModeResolver } from "./agent/models/AgentModeResolver.js";
-import { AgentRuntime } from "./agent/runtime/AgentRuntime.js";
-import { SpeechTurnService } from "./agent/speech/SpeechTurnService.js";
-import { AgentToolProvider } from "./agent/tools/AgentToolProvider.js";
-import { TurnContextBuilder } from "./agent/turn/TurnContextBuilder.js";
-import { TurnLifecycleService } from "./agent/turn/TurnLifecycleService.js";
-import { TurnPersistenceService } from "./agent/turn/TurnPersistenceService.js";
-import { TurnPromptBuilder } from "./agent/turn/TurnPromptBuilder.js";
-import { TurnStreamConsumer } from "./agent/turn/TurnStreamConsumer.js";
-
-export type { AgentEvent, AgentEventEmitter } from "./agentEvents.js";
-
-export default class AdminForthAgentPlugin extends AdminForthPlugin {
-  options: PluginOptions;
-  agentSystemPromptPromise: Promise<string>;
-  pluginsScope: "resource" | "global" = "global";
-  private agentSystemPrompt: string | null = null;
-  private checkpointer: BaseCheckpointSaver | null = null;
-  private sessionStore: AgentSessionStore;
-  private agentTurnService: AgentTurnService;
-  private speechTurnService: SpeechTurnService;
-  private chatSurfaceService: ChatSurfaceService;
-  private getCheckpointer() {
-    if (this.checkpointer) return this.checkpointer;
-
-    this.checkpointer = this.options.checkpointResource
-      ? new AdminForthCheckpointSaver(this.adminforth, this.options)
-      : new MemorySaver();
-
-    return this.checkpointer;
-  }
-
-  private getInternalAgentResourceIds() {
-    return [
-      this.options.sessionResource.resourceId,
-      this.options.turnResource.resourceId,
-      this.options.checkpointResource?.resourceId,
-    ].filter((resourceId): resourceId is string => Boolean(resourceId));
-  }
-
-  constructor(options: PluginOptions) {
-    super(options, import.meta.url);
-    this.options = options;
-    this.sessionStore = new AgentSessionStore(() => this.adminforth, this.options);
-    const toolProvider = new AgentToolProvider(
-      () => this.adminforth,
-      this.getInternalAgentResourceIds.bind(this),
-    );
-    const runtime = new AgentRuntime({
-      name: `adminforth-agent-${this.pluginInstanceId}`,
-      getAdminforth: () => this.adminforth,
-      getCheckpointer: this.getCheckpointer.bind(this),
-      toolProvider,
-    });
-    const persistence = new TurnPersistenceService(() => this.adminforth, this.options);
-    this.agentTurnService = new AgentTurnService(
-      new TurnLifecycleService(this.sessionStore, persistence, this.options),
-      new TurnContextBuilder(() => this.adminforth),
-      new AgentModeResolver(this.options),
-      new AgentModelFactory(this.options.maxTokens ?? 1000),
-      new TurnPromptBuilder({
-        getAdminforth: () => this.adminforth,
-        getAgentSystemPrompt: async () => {
-          if (!this.agentSystemPrompt) {
-            const systemPrompt = await buildAgentSystemPrompt(
-              this.adminforth,
-              this.getInternalAgentResourceIds(),
-            ).catch((err) => {
-              return DEFAULT_AGENT_SYSTEM_PROMPT;
-            });
-            this.agentSystemPrompt = appendCustomSystemPrompt(systemPrompt, this.options.systemPrompt);
-          }
-          return this.agentSystemPrompt;
-        },
-      }),
-      runtime,
-      new TurnStreamConsumer(),
-    );
-    this.speechTurnService = new SpeechTurnService(
-      this.agentTurnService.runAndPersistAgentResponse.bind(this.agentTurnService),
-    );
-    this.chatSurfaceService = new ChatSurfaceService(
-      () => this.adminforth,
-      this.options,
-      this.sessionStore,
-      this.agentTurnService.handleTurn.bind(this.agentTurnService),
-      this.agentTurnService.runAndPersistAgentResponse.bind(this.agentTurnService),
-    );
-    this.agentSystemPromptPromise = Promise.resolve(
-      appendCustomSystemPrompt(DEFAULT_AGENT_SYSTEM_PROMPT, this.options.systemPrompt),
-    );
-    this.shouldHaveSingleInstancePerWholeApp = () => false;
-  }
-
-  async modifyGlobalConfig(adminforth: IAdminForth) {
-    super.modifyGlobalConfig(adminforth);
-    if (!this.options.modes?.length) {
-      throw new Error("modes is required for AdminForthAgentPlugin");
-    }
-    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,
-        modes: this.options.modes.map((mode) => ({ name: mode.name })),
-        defaultModeName: this.options.modes[0].name,
-        stickByDefault: this.options.stickByDefault ?? false,
-        hasAudioAdapter: Boolean(this.options.audioAdapter),
-      }
-    });
-    if (!this.adminforth.config.customization.customHeadItems) {
-      this.adminforth.config.customization.customHeadItems = [];
-    }
-    this.adminforth.config.customization.customHeadItems.push(
-      {
-        tagName: 'script',
-        attributes: {
-          src: 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.22.0/dist/ort.wasm.min.js'
-        }
-      },
-      {
-        tagName: 'script',
-        attributes: {
-          src: 'https://cdn.jsdelivr.net/npm/@ricky0123/vad-web@0.0.29/dist/bundle.min.js'
-        },
-      }
-    );
-    if (!this.options.sessionResource) {
-      throw new Error("sessionResource is required for AdminForthAgentPlugin");
-    }
-  }
-  
-  validateConfigAfterDiscover(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
-    this.options.audioAdapter?.validate();
-    for (const chatSurfaceAdapter of this.options.chatSurfaceAdapters ?? []) {
-      chatSurfaceAdapter.validate();
-    }
-    this.agentSystemPromptPromise = buildAgentSystemPrompt(
-      adminforth,
-      this.getInternalAgentResourceIds(),
-    )
-      .then((systemPrompt) => {
-        const finalPrompt = appendCustomSystemPrompt(systemPrompt, this.options.systemPrompt);
-        this.agentSystemPrompt = finalPrompt;
-        return finalPrompt;
-      });
-  }
-
-  instanceUniqueRepresentation(pluginOptions: any) : string {
-    return `single`;
-  }
-
-  setupEndpoints(server: IHttpServer) {
-    const endpointContext = {
-      adminforth: this.adminforth,
-      options: this.options,
-      handleTurn: this.agentTurnService.handleTurn.bind(this.agentTurnService),
-      handleSpeechTurn: this.speechTurnService.handle.bind(this.speechTurnService),
-      runAndPersistAgentResponse: this.agentTurnService.runAndPersistAgentResponse.bind(this.agentTurnService),
-      getSessionTurns: this.sessionStore.getSessionTurns.bind(this.sessionStore),
-      createNewTurn: this.sessionStore.createNewTurn.bind(this.sessionStore),
-      createSystemTurn: this.sessionStore.createSystemTurn.bind(this.sessionStore),
-      handleChatSurfaceMessage: this.chatSurfaceService.handleMessage.bind(this.chatSurfaceService),
-    } satisfies AgentEndpointsContext;
-
-    setupCoreEndpoints(endpointContext, server);
-    setupSessionEndpoints(endpointContext, server);
-    setupChatSurfaceEndpoints(endpointContext, server);
-  }
-}

package/pnpm-workspace.yaml

@@ -1,4 +0,0 @@
-allowBuilds:
-  adminforth: true
-minimumReleaseAgeExclude:
-  - adminforth

package/sanitizeSpeechText.ts

@@ -1,32 +0,0 @@
-const URL_RE = /\b(?:https?:\/\/|www\.)[^\s<>()]+/gi;
-const MARKDOWN_LINK_RE = /\[([^\]]+)]\(([^)]+)\)/g;
-const MARKDOWN_IMAGE_RE = /!\[([^\]]*)]\(([^)]+)\)/g;
-const HTML_TAG_RE = /<[^>]+>/g;
-const CODE_FENCE_RE = /```[\s\S]*?```/g;
-const INLINE_CODE_RE = /`[^`]*`/g;
-const BRACKETED_META_RE = /\[(?:ref|link|url|source|sources?|debug|meta|data):[^\]]*]/gi;
-const MD_HEADING_LINE_RE = /^\s{0,3}#{1,6}\s+/gm;
-const MD_BLOCKQUOTE_RE = /^\s{0,3}>\s?/gm;
-const MD_HR_RE = /^\s{0,3}(-{3,}|\*{3,}|_{3,})\s*$/gm;
-const MD_LIST_MARKER_RE = /^\s{0,3}(?:[-*+]|\d+\.)\s+/gm;
-const MD_EMPHASIS_RE = /(\*\*|__)(.*?)\1/g;
-const MD_ITALIC_RE = /(^|[^\\])(?:\*|_)([^\s].*?)(?:\*|_)/g;
-
-export function sanitizeSpeechText(input: string): string {
-  return input
-    .replace(CODE_FENCE_RE, " ")
-    .replace(MARKDOWN_IMAGE_RE, "$1")
-    .replace(MARKDOWN_LINK_RE, "$1")
-    .replace(URL_RE, " ")
-    .replace(MD_HEADING_LINE_RE, "")
-    .replace(MD_BLOCKQUOTE_RE, "")
-    .replace(MD_HR_RE, " ")
-    .replace(MD_LIST_MARKER_RE, "")
-    .replace(MD_EMPHASIS_RE, "$2")
-    .replace(MD_ITALIC_RE, "$1$2")
-    .replace(HTML_TAG_RE, " ")
-    .replace(INLINE_CODE_RE, " ")
-    .replace(BRACKETED_META_RE, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-}