@adminforth/agent 2.0.10 → 2.2.0

package/agent/tools/navigateUser.ts

@@ -1,210 +0,0 @@
-import { tool } from "langchain";
-import { z } from "zod";
-import type { CurrentPageContext } from "./getUserLocation.js";
-import type { AgentEventEmitter } from "../../agentEvents.js";
-
-const filterSchema = z.object({
-  column: z.string().min(1).describe("Resource column name."),
-  operator: z
-    .string()
-    .min(1)
-    .describe("Filter operator suffix, for example eq, gte, lte, like, in."),
-  value: z.unknown().describe("Filter value. Dates should be ISO strings."),
-});
-
-const navigateUserSchema = z
-  .object({
-    targetPath: z
-      .string()
-      .optional()
-      .describe(
-        "Root-relative AdminForth path to open, with optional query string and hash, for example /resource/adminuser?sort=created_at__desc.",
-      ),
-    resourceId: z
-      .string()
-      .optional()
-      .describe("Resource id to build an AdminForth resource route for."),
-    mode: z
-      .enum(["list", "show", "edit", "create"])
-      .optional()
-      .default("list")
-      .describe("Resource page mode. Defaults to list."),
-    recordId: z
-      .union([z.string(), z.number()])
-      .optional()
-      .describe("Record primary key for show or edit resource pages."),
-    filters: z
-      .array(filterSchema)
-      .optional()
-      .describe(
-        "List page filters. Each item becomes filter__{column}__{operator}=JSON.stringify(value).",
-      ),
-    sort: z
-      .object({
-        column: z.string().min(1),
-        direction: z.enum(["asc", "desc"]),
-      })
-      .optional()
-      .describe("List page sort. Becomes sort={column}__{direction}."),
-    query: z
-      .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
-      .optional()
-      .describe("Additional query parameters to append to the target URL."),
-  })
-  .refine((input) => input.targetPath || input.resourceId, {
-    message: "Either targetPath or resourceId is required.",
-  });
-
-function normalizeTargetPath(targetPath: string, currentPage?: CurrentPageContext) {
-  const trimmed = targetPath.trim();
-
-  if (!trimmed) {
-    throw new Error("targetPath cannot be empty.");
-  }
-
-  const currentOrigin = currentPage?.url ? new URL(currentPage.url).origin : undefined;
-
-  if (currentOrigin) {
-    const targetUrl = new URL(trimmed, currentOrigin);
-
-    if (targetUrl.origin !== currentOrigin) {
-      throw new Error("Only same-origin navigation targets are allowed.");
-    }
-
-    return `${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`;
-  }
-
-  const fallbackOrigin = "http://adminforth.local";
-  const targetUrl = new URL(trimmed, fallbackOrigin);
-
-  if (targetUrl.origin !== fallbackOrigin) {
-    throw new Error("Only relative AdminForth paths are allowed when current origin is unavailable.");
-  }
-
-  return `${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`;
-}
-
-function appendQueryParams(path: string, params: URLSearchParams) {
-  const queryString = params.toString();
-
-  if (!queryString) {
-    return path;
-  }
-
-  const hashIndex = path.indexOf("#");
-  const pathWithoutHash = hashIndex === -1 ? path : path.slice(0, hashIndex);
-  const hash = hashIndex === -1 ? "" : path.slice(hashIndex);
-  const separator = pathWithoutHash.includes("?") ? "&" : "?";
-
-  return `${pathWithoutHash}${separator}${queryString}${hash}`;
-}
-
-function buildResourcePath(input: z.infer<typeof navigateUserSchema>) {
-  if (!input.resourceId) {
-    throw new Error("resourceId is required to build a resource route.");
-  }
-
-  const resourceId = encodeURIComponent(input.resourceId);
-  const mode = input.mode ?? "list";
-
-  if (mode === "show" || mode === "edit") {
-    if (input.recordId === undefined || input.recordId === null) {
-      throw new Error(`recordId is required for ${mode} resource pages.`);
-    }
-
-    return `/resource/${resourceId}/${mode}/${encodeURIComponent(String(input.recordId))}`;
-  }
-
-  if (mode === "create") {
-    return `/resource/${resourceId}/create`;
-  }
-
-  return `/resource/${resourceId}`;
-}
-
-function buildQueryParams(input: z.infer<typeof navigateUserSchema>) {
-  const params = new URLSearchParams();
-
-  for (const filter of input.filters ?? []) {
-    params.set(
-      `filter__${filter.column}__${filter.operator}`,
-      JSON.stringify(filter.value),
-    );
-  }
-
-  if (input.sort) {
-    params.set("sort", `${input.sort.column}__${input.sort.direction}`);
-  }
-
-  for (const [key, value] of Object.entries(input.query ?? {})) {
-    params.set(key, String(value));
-  }
-
-  return params;
-}
-
-function buildSurfaceUrl(targetPath: string, adminBaseUrl?: string, adminPublicOrigin?: string) {
-  const normalizedBasePath = adminBaseUrl?.replace(/\/+$/, "") ?? "";
-  const normalizedTargetPath = targetPath.replace(/^\/+/, "");
-  const path = `${normalizedBasePath}/${normalizedTargetPath}`;
-
-  return adminPublicOrigin ? new URL(path, adminPublicOrigin).toString() : path;
-}
-
-export function createNavigateUserTool() {
-  return tool(
-    async (input, runtime) => {
-      const context = runtime.context as {
-        currentPage?: CurrentPageContext;
-        chatSurface?: string;
-        adminBaseUrl?: string;
-        adminPublicOrigin?: string;
-        emit?: AgentEventEmitter;
-      };
-      const currentPage = context.currentPage;
-      const basePath = input.targetPath
-        ? normalizeTargetPath(input.targetPath, currentPage)
-        : buildResourcePath(input);
-      const targetPath = appendQueryParams(basePath, buildQueryParams(input));
-
-      if (context.chatSurface) {
-        const url = buildSurfaceUrl(targetPath, context.adminBaseUrl, context.adminPublicOrigin);
-
-        return JSON.stringify(
-          {
-            status: 200,
-            action: "link",
-            surface: context.chatSurface,
-            targetPath,
-            url,
-            message: `Send this link to the user: ${url}`,
-          },
-          null,
-          2,
-        );
-      }
-
-      await context.emit?.({
-        type: "open-page",
-        targetPath,
-      });
-
-      return JSON.stringify(
-        {
-          status: 200,
-          action: "navigate",
-          targetPath,
-          message: `Navigation requested to ${targetPath}.`,
-        },
-        null,
-        2,
-      );
-    },
-    {
-      name: "navigate_user",
-      description:
-        "Navigate the user to another AdminForth page. Use this only when the user asks to open, show, go to, or switch to a resource list/detail page, including filtered or sorted resource lists. Or if the user is asked to open something on the left. Do not use this tool in any other case.",
-      schema: navigateUserSchema,
-    },
-  );
-}

package/agent/turn/TurnContextBuilder.ts

@@ -1,36 +0,0 @@
-import type { AdminUser, IAdminForth } from "adminforth";
-import type { AgentTurnContext, BaseAgentTurnInput } from "./turnTypes.js";
-
-export type UserContextProvider = {
-  getUserTimeZone(adminUser: AdminUser): Promise<string | null | undefined> | string | null | undefined;
-};
-
-export class TurnContextBuilder {
-  constructor(
-    private readonly getAdminforth: () => IAdminForth,
-    private readonly userContextProvider?: UserContextProvider,
-  ) {}
-
-  async build(input: {
-    base: BaseAgentTurnInput;
-    turnId: string;
-  }): Promise<AgentTurnContext> {
-    const adminforth = this.getAdminforth();
-
-    return {
-      adminUser: input.base.adminUser,
-      sessionId: input.base.sessionId,
-      turnId: input.turnId,
-      abortSignal: input.base.abortSignal,
-      currentPage: input.base.currentPage,
-      chatSurface: input.base.chatSurface,
-      userTimeZone:
-        input.base.userTimeZone
-        ?? await this.userContextProvider?.getUserTimeZone(input.base.adminUser)
-        ?? "UTC",
-      adminPublicOrigin:
-        input.base.adminPublicOrigin
-        ?? adminforth.config.baseUrlSlashed,
-    };
-  }
-}

package/agent/turn/TurnLifecycleService.ts

@@ -1,47 +0,0 @@
-import type { AgentSessionStore } from "../../sessionStore.js";
-import type { PluginOptions } from "../../types.js";
-import type { BaseAgentTurnInput } from "./turnTypes.js";
-import { TurnPersistenceService } from "./TurnPersistenceService.js";
-
-export class TurnLifecycleService {
-  constructor(
-    private readonly sessionStore: AgentSessionStore,
-    private readonly persistence: TurnPersistenceService,
-    private readonly options: PluginOptions,
-  ) {}
-
-  async start(input: BaseAgentTurnInput) {
-    const previousUserMessages = await this.sessionStore.getPreviousUserMessages(input.sessionId);
-    const turnId = await this.sessionStore.createNewTurn(input.sessionId, input.prompt);
-    await this.persistence.touchSession(input.sessionId);
-
-    return {
-      turnId,
-      previousUserMessages,
-    };
-  }
-
-  async resume(input: BaseAgentTurnInput) {
-    const latestTurn = await this.sessionStore.getLatestTurn(input.sessionId);
-
-    if (!latestTurn) {
-      throw new Error(`No agent turn found for session "${input.sessionId}".`);
-    }
-
-    return {
-      turnId: latestTurn[this.options.turnResource.idField],
-      previousUserMessages: await this.sessionStore.getPreviousUserMessages(input.sessionId),
-      initialResponse: latestTurn[this.options.turnResource.responseField] === "not_finished"
-        ? ""
-        : String(latestTurn[this.options.turnResource.responseField]),
-    };
-  }
-
-  async finish(input: {
-    turnId: string;
-    responseText: string;
-    debugHistory?: unknown;
-  }) {
-    await this.persistence.saveTurnResponse(input);
-  }
-}

package/agent/turn/TurnPersistenceService.ts

@@ -1,33 +0,0 @@
-import type { IAdminForth } from "adminforth";
-import type { PluginOptions } from "../../types.js";
-
-export class TurnPersistenceService {
-  constructor(
-    private readonly getAdminforth: () => IAdminForth,
-    private readonly options: PluginOptions,
-  ) {}
-
-  async touchSession(sessionId: string) {
-    await this.getAdminforth().resource(this.options.sessionResource.resourceId).update(sessionId, {
-      [this.options.sessionResource.createdAtField]: new Date().toISOString(),
-    });
-  }
-
-  async saveTurnResponse(input: {
-    turnId: string;
-    responseText: string;
-    debugHistory?: unknown;
-  }) {
-    const turnUpdates: Record<string, unknown> = {
-      [this.options.turnResource.responseField]: input.responseText,
-    };
-
-    if (this.options.turnResource.debugField) {
-      turnUpdates[this.options.turnResource.debugField] = input.debugHistory;
-    }
-
-    await this.getAdminforth()
-      .resource(this.options.turnResource.resourceId)
-      .update(input.turnId, turnUpdates);
-  }
-}

package/agent/turn/TurnPromptBuilder.ts

@@ -1,51 +0,0 @@
-import type { AdminUser, IAdminForth } from "adminforth";
-import { logger } from "adminforth";
-import { HumanMessage, SystemMessage } from "langchain";
-import { detectUserLanguage, type PreviousUserMessage } from "../languageDetect.js";
-import { buildAgentTurnSystemPrompt } from "../systemPrompt.js";
-import { getErrorMessage, isAbortError } from "../../errors.js";
-import type { AgentModeCompletionAdapter } from "../simpleAgent.js";
-
-export class TurnPromptBuilder {
-  constructor(
-    private readonly options: {
-      getAgentSystemPrompt: () => Promise<string>;
-      getAdminforth: () => IAdminForth;
-    },
-  ) {}
-
-  async build(input: {
-    prompt: string;
-    previousUserMessages: PreviousUserMessage[];
-    adminUser: AdminUser;
-    completionAdapter: AgentModeCompletionAdapter;
-    chatSurface?: string;
-    abortSignal?: AbortSignal;
-  }) {
-    const adminforth = this.options.getAdminforth();
-    const userLanguage = await detectUserLanguage(
-      input.completionAdapter,
-      input.prompt,
-      input.previousUserMessages,
-    ).catch((error) => {
-      if (input.abortSignal?.aborted || isAbortError(error)) {
-        throw error;
-      }
-
-      logger.warn(`Failed to detect user language: ${getErrorMessage(error)}`);
-      return null;
-    });
-    const systemPrompt = buildAgentTurnSystemPrompt({
-      agentSystemPrompt: await this.options.getAgentSystemPrompt(),
-      adminUser: input.adminUser,
-      usernameField: adminforth.config.auth!.usernameField,
-      userLanguage,
-      chatSurface: input.chatSurface,
-    });
-
-    return [
-      new SystemMessage(systemPrompt),
-      new HumanMessage(input.prompt),
-    ];
-  }
-}

package/agent/turn/TurnStreamConsumer.ts

@@ -1,69 +0,0 @@
-import type { AgentEventEmitter } from "../../agentEvents.js";
-import { VegaLiteStreamBuffer } from "./VegaLiteStreamBuffer.js";
-
-export class TurnStreamConsumer {
-  async consume(input: {
-    stream: AsyncIterable<["messages", [any, any]] | ["updates", Record<string, any>]>;
-    abortSignal?: AbortSignal;
-    emit?: AgentEventEmitter;
-    onInterrupt?: (interrupt: unknown) => void | Promise<void>;
-  }) {
-    let fullResponse = "";
-    const textBuffer = new VegaLiteStreamBuffer();
-
-    for await (const [mode, chunk] of input.stream) {
-      if (input.abortSignal?.aborted) {
-        throw new DOMException("This operation was aborted", "AbortError");
-      }
-
-      if (mode === "updates") {
-        if ("__interrupt__" in chunk) {
-          await input.onInterrupt?.(chunk.__interrupt__);
-        }
-        continue;
-      }
-
-      const [token, metadata] = chunk;
-      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((block: any) => block?.type === "reasoning")
-        .map((block: any) => String(block.reasoning ?? ""))
-        .join("");
-      const textDelta = blocks
-        .filter((block: any) => block?.type === "text")
-        .map((block: any) => String(block.text ?? ""))
-        .join("");
-
-      if (reasoningDelta) {
-        await input.emit?.({
-          type: "reasoning-delta",
-          delta: reasoningDelta,
-        });
-      }
-
-      if (textDelta) {
-        fullResponse += textDelta;
-        await textBuffer.push(textDelta, input.emit);
-      }
-    }
-
-    await textBuffer.flush(input.emit);
-
-    return {
-      text: fullResponse,
-    };
-  }
-}

package/agent/turn/VegaLiteStreamBuffer.ts

@@ -1,90 +0,0 @@
-import type { AgentEventEmitter } from "../../agentEvents.js";
-
-const VEGA_LITE_FENCE_START = "```vega-lite";
-const FENCE_END = "```";
-
-export class VegaLiteStreamBuffer {
-  private bufferedTextDelta = "";
-  private isRenderingVegaLite = false;
-
-  async push(textDelta: string, emit?: AgentEventEmitter) {
-    this.bufferedTextDelta += textDelta;
-
-    if (
-      hasUnclosedLatestVegaLiteBlock(this.bufferedTextDelta)
-    ) {
-      if (!this.isRenderingVegaLite) {
-        this.isRenderingVegaLite = true;
-        await emit?.({
-          type: "rendering",
-          phase: "start",
-          label: "Rendering...",
-        });
-      }
-      return;
-    }
-
-    if (this.isRenderingVegaLite) {
-      this.isRenderingVegaLite = false;
-      await emit?.({
-        type: "rendering",
-        phase: "end",
-        label: "Rendering...",
-      });
-    }
-
-    const streamableLength = this.bufferedTextDelta.includes(VEGA_LITE_FENCE_START)
-      ? this.bufferedTextDelta.length
-      : this.bufferedTextDelta.length - getPartialVegaLiteFenceStartLength(this.bufferedTextDelta);
-
-    if (!streamableLength) {
-      return;
-    }
-
-    await emit?.({
-      type: "text-delta",
-      delta: this.bufferedTextDelta.slice(0, streamableLength),
-    });
-    this.bufferedTextDelta = this.bufferedTextDelta.slice(streamableLength);
-  }
-
-  async flush(emit?: AgentEventEmitter) {
-    if (this.isRenderingVegaLite) {
-      await emit?.({
-        type: "rendering",
-        phase: "end",
-        label: "Rendering...",
-      });
-      this.isRenderingVegaLite = false;
-    }
-
-    if (this.bufferedTextDelta) {
-      await emit?.({
-        type: "text-delta",
-        delta: this.bufferedTextDelta,
-      });
-      this.bufferedTextDelta = "";
-    }
-  }
-}
-
-function hasUnclosedLatestVegaLiteBlock(text: string): boolean {
-  const latestBlockStart = text.lastIndexOf(VEGA_LITE_FENCE_START);
-
-  if (latestBlockStart === -1) {
-    return false;
-  }
-
-  const blockContentStart = latestBlockStart + VEGA_LITE_FENCE_START.length;
-  return text.indexOf(FENCE_END, blockContentStart) === -1;
-}
-
-function getPartialVegaLiteFenceStartLength(text: string): number {
-  for (let length = Math.min(text.length, VEGA_LITE_FENCE_START.length - 1); length > 0; length -= 1) {
-    if (VEGA_LITE_FENCE_START.startsWith(text.slice(-length))) {
-      return length;
-    }
-  }
-
-  return 0;
-}

package/agent/turn/turnTypes.ts

@@ -1,100 +0,0 @@
-import type { AdminUser, AudioAdapter } from "adminforth";
-import type { Messages } from "@langchain/langgraph";
-import type { Command } from "@langchain/langgraph";
-import type { AgentChatModel, AgentMiddleware } from "../simpleAgent.js";
-import type { SequenceDebugCollector } from "../middleware/sequenceDebug.js";
-import type { PreviousUserMessage } from "../languageDetect.js";
-import type { CurrentPageContext } from "../tools/getUserLocation.js";
-import type { AgentEventEmitter } from "../../agentEvents.js";
-
-export type BaseAgentTurnInput = {
-  prompt: string;
-  sessionId: string;
-  modeName?: string | null;
-  userTimeZone?: string;
-  currentPage?: CurrentPageContext;
-  chatSurface?: string;
-  adminPublicOrigin?: string;
-  abortSignal?: AbortSignal;
-  adminUser: AdminUser;
-};
-
-export type TextAgentTurnInput = BaseAgentTurnInput & {
-  emit: AgentEventEmitter;
-  approvalDecision?: "approve" | "reject";
-  failureLogMessage?: string;
-  abortLogMessage?: string;
-};
-
-export type SpeechAgentTurnInput = Omit<BaseAgentTurnInput, "prompt"> & {
-  emit: AgentEventEmitter;
-  audioAdapter: AudioAdapter;
-  audio: {
-    buffer: Buffer;
-    filename: string;
-    mimeType: string;
-  };
-  failureLogMessage?: string;
-  abortLogMessage?: string;
-};
-
-export type AgentTurnContext = {
-  adminUser: AdminUser;
-  userTimeZone: string;
-  sessionId: string;
-  turnId: string;
-  abortSignal?: AbortSignal;
-  currentPage?: CurrentPageContext;
-  chatSurface?: string;
-  adminPublicOrigin?: string;
-};
-
-export type AgentTurnObservability = {
-  emit?: AgentEventEmitter;
-  sequenceDebugSink: SequenceDebugCollector;
-};
-
-export type PreparedAgentTurn = {
-  prompt: string;
-  sessionId: string;
-  turnId: string;
-  previousUserMessages: PreviousUserMessage[];
-  modeName?: string | null;
-  context: AgentTurnContext;
-  observability: AgentTurnObservability;
-  resume?: {
-    decision: "approve" | "reject";
-    interrupts?: { id: string; count: number }[];
-  };
-  initialResponse?: string;
-};
-
-export type AgentTurnModels = {
-  model: AgentChatModel;
-  summaryModel: AgentChatModel;
-  modelMiddleware?: AgentMiddleware[];
-};
-
-export type AgentRuntimeRunInput = {
-  models: AgentTurnModels;
-  input: { messages: Messages } | Command;
-  context: AgentTurnContext;
-  observability: AgentTurnObservability;
-};
-
-export type RunAndPersistAgentResponseInput = BaseAgentTurnInput & {
-  emit?: AgentEventEmitter;
-  approvalDecision?: "approve" | "reject";
-  failureLogMessage: string;
-  abortLogMessage: string;
-};
-
-export type RunAndPersistAgentResponseResult = {
-  text: string;
-  turnId: string;
-  aborted: boolean;
-  failed: boolean;
-};
-
-export type HandleTurnInput = TextAgentTurnInput;
-export type HandleSpeechTurnInput = SpeechAgentTurnInput;