@adminforth/agent 2.0.10 → 2.1.0

package/agent/toolCallEvents.ts

@@ -1,135 +0,0 @@
-import { randomUUID } from "crypto";
-import YAML from "yaml";
-
-export type ToolCallEvent =
-  | {
-      toolCallId: string;
-      toolName: string;
-      toolInfo?: string;
-      phase: "start";
-      input: string;
-    }
-  | {
-      toolCallId: string;
-      toolName: string;
-      phase: "end";
-      durationMs: number;
-      output: string | null;
-      error: string | null;
-    };
-
-export type ToolCallEventSink = (event: ToolCallEvent) => void;
-
-const TOOL_MESSAGE_DEBUG_KEYS = new Set([
-  "metadata",
-  "additional_kwargs",
-  "response_metadata",
-]);
-
-function getToolCallDebugPayload(outputRecord: Record<string, unknown>) {
-  const lcKwargs =
-    typeof outputRecord.lc_kwargs === "object" && outputRecord.lc_kwargs !== null
-      ? outputRecord.lc_kwargs as Record<string, unknown>
-      : null;
-
-  if (lcKwargs && "tool_call_id" in lcKwargs) {
-    return lcKwargs;
-  }
-
-  if ("tool_call_id" in outputRecord) {
-    return outputRecord;
-  }
-
-  return null;
-}
-
-function sanitizeToolCallOutputForDebug(output: unknown) {
-  if (typeof output !== "object" || output === null) {
-    return output;
-  }
-
-  const outputRecord = output as Record<string, unknown>;
-  const debugPayload = getToolCallDebugPayload(outputRecord);
-
-  if (!debugPayload) {
-    return output;
-  }
-
-  return Object.fromEntries(
-    Object.entries(debugPayload).filter(([key]) => !TOOL_MESSAGE_DEBUG_KEYS.has(key)),
-  );
-}
-
-function serializeErrorForDebug(error: unknown): unknown {
-  if (!(error instanceof Error)) {
-    return error;
-  }
-
-  const errorWithCause = error as Error & { cause?: unknown };
-  const serialized: Record<string, unknown> = {
-    name: error.name,
-    message: error.message,
-  };
-
-  if (error.stack) {
-    serialized.stack = error.stack;
-  }
-
-  if (errorWithCause.cause !== undefined) {
-    serialized.cause = serializeErrorForDebug(errorWithCause.cause);
-  }
-
-  for (const key of Object.getOwnPropertyNames(error)) {
-    if (key in serialized) {
-      continue;
-    }
-
-    serialized[key] = (error as unknown as Record<string, unknown>)[key];
-  }
-
-  return serialized;
-}
-
-export function createToolCallTracker(params: {
-  emit: ToolCallEventSink;
-  toolCallId?: string;
-  toolName: string;
-  toolInfo?: string;
-  input?: Record<string, unknown>;
-  startedAt?: number;
-}) {
-  const toolCallId = params.toolCallId ?? randomUUID();
-  const startedAt = params.startedAt ?? Date.now();
-
-  return {
-    start() {
-      params.emit({
-        toolCallId,
-        toolName: params.toolName,
-        toolInfo: params.toolInfo,
-        phase: "start",
-        input: YAML.stringify(params.input ?? {}),
-      });
-    },
-    finishSuccess(output: unknown) {
-      params.emit({
-        toolCallId,
-        toolName: params.toolName,
-        phase: "end",
-        durationMs: Date.now() - startedAt,
-        output: YAML.stringify(sanitizeToolCallOutputForDebug(output)).trimEnd(),
-        error: null,
-      });
-    },
-    finishError(error: unknown) {
-      params.emit({
-        toolCallId,
-        toolName: params.toolName,
-        phase: "end",
-        durationMs: Date.now() - startedAt,
-        output: null,
-        error: YAML.stringify(serializeErrorForDebug(error)).trimEnd(),
-      });
-    },
-  };
-}

package/agent/tools/AgentToolProvider.ts

@@ -1,28 +0,0 @@
-import type { IAdminForth } from "adminforth";
-import { prepareApiBasedTools } from "../../apiBasedTools.js";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
-import { createAgentTools } from "./index.js";
-
-export class AgentToolProvider {
-  constructor(
-    private readonly getAdminforth: () => IAdminForth,
-    private readonly getInternalAgentResourceIds: () => string[],
-  ) {}
-
-  getApiBasedTools(): Record<string, ApiBasedTool> {
-    return prepareApiBasedTools(
-      this.getAdminforth(),
-      this.getInternalAgentResourceIds(),
-    );
-  }
-
-  async getTools(apiBasedTools: Record<string, ApiBasedTool>) {
-    const adminforth = this.getAdminforth();
-
-    return createAgentTools(
-      adminforth.config.customization.customComponentsDir ?? "custom",
-      apiBasedTools,
-      adminforth.activatedPlugins.map((plugin) => plugin.customFolderPath),
-    );
-  }
-}

package/agent/tools/apiTool.ts

@@ -1,66 +0,0 @@
-import { tool } from "langchain";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
-
-const emptyToolSchema = {
-  type: "object",
-  properties: {},
-  additionalProperties: true,
-} as const;
-
-function normalizeToolInputSchema(inputSchema: unknown) {
-  if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
-    return emptyToolSchema;
-  }
-
-  const schema = JSON.parse(JSON.stringify(inputSchema)) as Record<string, unknown>;
-
-  if (schema.type !== "object") {
-    return emptyToolSchema;
-  }
-
-  const notes: string[] = [];
-
-  if ("if" in schema || "then" in schema || "else" in schema || "allOf" in schema) {
-    delete schema.if;
-    delete schema.then;
-    delete schema.else;
-    delete schema.allOf;
-    notes.push("Runtime applies additional conditional validation rules.");
-  }
-
-  if ("oneOf" in schema || "anyOf" in schema || "not" in schema || "enum" in schema) {
-    delete schema.oneOf;
-    delete schema.anyOf;
-    delete schema.not;
-    delete schema.enum;
-    notes.push("Top-level composite validation rules are omitted for tool compatibility.");
-  }
-
-  if (notes.length > 0) {
-    schema.description = typeof schema.description === "string"
-      ? `${schema.description}\n\n${notes.join(" ")}`
-      : notes.join(" ");
-  }
-
-  return schema;
-}
-
-export function createApiTool(toolName: string, apiBasedTool: ApiBasedTool) {
-  return tool(
-    async (input, runtime) => {
-      const normalizedInput = (input ?? {}) as Record<string, unknown>;
-      return apiBasedTool.call({
-        adminUser: runtime.context.adminUser,
-        abortSignal: runtime.context.abortSignal,
-        inputs: normalizedInput,
-        userTimeZone: runtime.context.userTimeZone,
-      });
-    },
-    {
-      name: toolName,
-      description: apiBasedTool.description ?? `${toolName} tool`,
-      schema: normalizeToolInputSchema(apiBasedTool.input_schema),
-      verboseParsingErrors: true,
-    },
-  );
-}

package/agent/tools/fetchSkill.ts

@@ -1,68 +0,0 @@
-import { tool } from "langchain";
-import { z } from "zod";
-import {
-  listSkillManifests,
-  loadSkillMarkdown,
-  type AgentSkillManifest,
-} from "../skills/registry.js";
-
-const fetchSkillSchema = z.object({
-  skillName: z
-    .string()
-    .describe(
-      "Name of the custom AdminForth skill to load, for example fetch_data or mutate_data.",
-    ),
-});
-
-function serializeSkillManifests(skillManifests: AgentSkillManifest[]) {
-  return skillManifests.map((skill) => ({
-    name: skill.name,
-    description: skill.description,
-  }));
-}
-
-export async function createFetchSkillTool(
-  customComponentsDir: string,
-  pluginCustomFolderPaths: string[] = [],
-) {
-  const availableSkills = await listSkillManifests(
-    customComponentsDir,
-    pluginCustomFolderPaths,
-  );
-  const availableSkillNames = availableSkills.map((skill) => skill.name);
-
-  return tool(
-    async ({ skillName }) => {
-      try {
-        const skillMarkdown = await loadSkillMarkdown(
-          skillName,
-          customComponentsDir,
-          pluginCustomFolderPaths,
-        );
-
-        if (!skillMarkdown) {
-          return [
-            `Skill "${skillName}" not found.`,
-            "Available skills:",
-            JSON.stringify(serializeSkillManifests(availableSkills), null, 2),
-          ].join("\n");
-        }
-
-        return skillMarkdown;
-      } catch (error) {
-        return `Failed to load skill "${skillName}": ${
-          error instanceof Error ? error.message : String(error)
-        }`;
-      }
-    },
-    {
-      name: "fetch_skill",
-      description: `Fetch the raw SKILL.md content for a custom AdminForth skill by name.${
-        availableSkillNames.length > 0
-          ? ` Available skills: ${availableSkillNames.join(", ")}.`
-          : ""
-      }`,
-      schema: fetchSkillSchema,
-    },
-  );
-}

package/agent/tools/fetchToolSchema.ts

@@ -1,47 +0,0 @@
-import { tool } from "langchain";
-import { z } from "zod";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
-
-const fetchToolSchemaSchema = z.object({
-  toolName: z
-    .string()
-    .describe("Name of the API-based tool to load, for example get_resource."),
-});
-
-export async function createFetchToolSchemaTool(
-  apiBasedTools: Record<string, ApiBasedTool>,
-) {
-  return tool(
-    async ({ toolName }) => {
-      const toolDefinition = apiBasedTools[toolName];
-
-      if (!toolDefinition) {
-        return JSON.stringify(
-          {
-            status: 404,
-            error: "TOOL_NOT_FOUND",
-            message: `Tool "${toolName}" not found.`,
-          },
-          null,
-          2,
-        );
-      }
-
-      return JSON.stringify(
-        {
-          status: 200,
-          name: toolName,
-          loaded: true,
-        },
-        null,
-        2,
-      );
-    },
-    {
-      name: "fetch_tool_schema",
-      description:
-        "Fetch the schema for an API-based AdminForth tool by name and load it for later use. Use this right after fetch_skill when the skill mentions non-base tools.",
-      schema: fetchToolSchemaSchema,
-    },
-  );
-}

package/agent/tools/getUserLocation.ts

@@ -1,45 +0,0 @@
-import { tool } from "langchain";
-import { z } from "zod";
-
-export type CurrentPageContext = {
-  path: string;
-  fullPath: string;
-  title: string;
-  url: string;
-};
-
-const getUserLocationSchema = z.object({});
-
-export function createGetUserLocationTool() {
-  return tool(
-    async (_input, runtime) => {
-      const currentPage = (runtime.context as { currentPage?: CurrentPageContext }).currentPage;
-
-      if (!currentPage) {
-        return JSON.stringify(
-          {
-            status: 404,
-            message: "Current user location is not available.",
-          },
-          null,
-          2,
-        );
-      }
-
-      return JSON.stringify(
-        {
-          status: 200,
-          location: currentPage,
-        },
-        null,
-        2,
-      );
-    },
-    {
-      name: "get_user_location",
-      description:
-        "Get the user's current location in the AdminForth UI, including current page path, full path, title, and URL. Call this tool when you do not understand what the user is referring to, especially when they say here, this page, current page, opened page, or otherwise rely on page context.",
-      schema: getUserLocationSchema,
-    },
-  );
-}

package/agent/tools/index.ts

@@ -1,31 +0,0 @@
-import type { ClientTool } from "@langchain/core/tools";
-import { createFetchSkillTool } from "./fetchSkill.js";
-import { createFetchToolSchemaTool } from "./fetchToolSchema.js";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
-import { createApiTool } from "./apiTool.js";
-import { createGetUserLocationTool } from "./getUserLocation.js";
-import { createNavigateUserTool } from "./navigateUser.js";
-
-export const ALWAYS_AVAILABLE_API_TOOL_NAMES = ["get_resource"] as const;
-
-export async function createAgentTools(
-  customComponentsDir: string,
-  apiBasedTools: Record<string, ApiBasedTool>,
-  pluginCustomFolderPaths: string[] = [],
-): Promise<ClientTool[]> {
-  return [
-    ...ALWAYS_AVAILABLE_API_TOOL_NAMES.map((toolName) => {
-      const apiBasedTool = apiBasedTools[toolName];
-
-      if (!apiBasedTool) {
-        throw new Error(`Required base API tool "${toolName}" is missing.`);
-      }
-
-      return createApiTool(toolName, apiBasedTool);
-    }),
-    createGetUserLocationTool(),
-    createNavigateUserTool(),
-    await createFetchSkillTool(customComponentsDir, pluginCustomFolderPaths),
-    await createFetchToolSchemaTool(apiBasedTools),
-  ];
-}

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