@adminforth/agent 2.0.10 → 2.2.0

package/agent/systemPrompt.ts

@@ -1,133 +0,0 @@
-import type { AdminForthResource, AdminUser, IAdminForth } from "adminforth";
-import type { DetectedLanguage } from "./languageDetect.js";
-import {
-  listProjectSkillManifests,
-  type AgentSkillManifest,
-} from "./skills/registry.js";
-
-export const DEFAULT_AGENT_SYSTEM_PROMPT = [
-  "You are helpful AI Assistant for Admin Panel.",
-  
-  // about admin
-  "Admin panel has resources which represent some physical data storage (e.g. table/collection), each resource defines list of columns.",
-  "Each resource stores data records. Record represents a data item of resource.",
-  
-  //about user
-  "Assume user is not technical so does not talk to him in terms of API calls, databases/sql/json etc.",
-  
-  // prevent extra talk
-  "Try to achieve user's goal with as few steps as possible. Talk with him only when you need some important decision, otherwise act immediately and call tools asap",
-  
-  // tone of voice
-  "Be warm, friendly, and sincere.",
-  "Keep responses short, clear, and practical.",
-  "Answer only what is needed.",
-  "Do not add extra explanations or suggestions unless the user asks.",
-  "Adapt to the user's tone and style of speaking, mirroring their vibe and wording.",
-  "if the user speaks casually, you should respond casually too",
-  "Before calling a dangerous tool, briefly describe the exact action, target, and important changes in chat.",
-  "Do not ask the user for textual confirmation; dangerous tools are approved by the runtime approval UI.",
-].join(" ");
-
-export function appendCustomSystemPrompt(
-  systemPrompt: string,
-  customSystemPrompt?: string,
-) {
-  const normalizedCustomSystemPrompt = customSystemPrompt?.trim();
-
-  if (!normalizedCustomSystemPrompt) {
-    return systemPrompt;
-  }
-
-  return `${systemPrompt}\n\n${normalizedCustomSystemPrompt}`;
-}
-
-function formatLanguagePrompt(language: DetectedLanguage | null) {
-  if (!language || language.ambiguous) {
-    return "Respond in the user's language.";
-  }
-
-  return `Respond in ${language.language} (${language.code}).`;
-}
-
-function formatAdminUserPrompt(adminUser: AdminUser, usernameField: string) {
-  const adminUserContext = {
-    id: adminUser.pk,
-    email: adminUser.dbUser[usernameField],
-  };
-  return [
-    "Current admin user context:",
-    JSON.stringify(adminUserContext, null, 2),
-    "Use this admin user email when the user asks to send information to themselves, the current admin, or the logged-in user.",
-  ].join("\n");
-}
-
-export function buildAgentTurnSystemPrompt(input: {
-  agentSystemPrompt: string;
-  adminUser: AdminUser;
-  usernameField: string;
-  userLanguage: DetectedLanguage | null;
-  chatSurface?: string;
-}) {
-  return [
-    input.agentSystemPrompt,
-    formatAdminUserPrompt(input.adminUser, input.usernameField),
-    input.chatSurface
-      ? `Current chat surface: ${input.chatSurface}. The user is not in the AdminForth web UI, so tools cannot move their browser. When navigate_user returns a link, send that link to the user.`
-      : "",
-    formatLanguagePrompt(input.userLanguage),
-  ].filter(Boolean).join("\n\n");
-}
-
-function formatResources(resources: AdminForthResource[]) {
-  return resources
-    .map((resource) => `- resourceId: ${resource.resourceId}\n  label: ${resource.label}`)
-    .join("\n");
-}
-
-function formatSkills(skills: AgentSkillManifest[], label: "skill_name" | "tool_name") {
-  return skills
-    .map((skill) => `- ${label}: ${skill.name}\n  description: ${skill.description}`)
-    .join("\n");
-}
-
-export async function buildAgentSystemPrompt(
-  adminforth: IAdminForth,
-  hiddenResourceIds: Iterable<string> = [],
-) {
-  const customComponentsDir = adminforth.config.customization.customComponentsDir ?? "custom";
-  const pluginCustomFolderPaths = adminforth.activatedPlugins
-    .map((plugin) => plugin.customFolderPath);
-  const skills = await listProjectSkillManifests(
-    customComponentsDir,
-    pluginCustomFolderPaths,
-  );
-  const adminBasePath = adminforth.config.baseUrlSlashed;
-  const hiddenResourceIdSet = new Set(hiddenResourceIds);
-  const visibleResources = adminforth.config.resources.filter(
-    (resource) => !hiddenResourceIdSet.has(resource.resourceId),
-  );
-  const sections = [
-    DEFAULT_AGENT_SYSTEM_PROMPT,
-    `ADMIN_BASE_PATH: ${adminBasePath}`,
-    `List of resources:\n${formatResources(visibleResources)}`,
-    skills.length > 0
-      ? `You have skills set:\n${formatSkills(skills, "skill_name")}`
-      : "",
-    "Before using any skill, call fetch_skill to load its full instructions.",
-    "The fetched skill response starts with 'Tools mentioned in this skill'. Read that list first.",
-    "You can use get_resource immediately to inspect resource structure and column names.",
-    "If the user wants to create, update, delete, or run actions on records, load mutate_data first.",
-    "If the user wants to fetch records, load fetch_data first. If the user wants analytics or charts, load analyze_data first.",
-    "Only call fetch_tool_schema for tool names that are explicitly mentioned in a fetched skill and are not already available as base tools.",
-    "If a fetched skill lists a non-base tool you need, call fetch_tool_schema for it immediately instead of telling the user the tool is unavailable.",
-    "For example: for record creation load mutate_data, read its tool list, call fetch_tool_schema for create_record, describe the planned record, and then use create_record.",
-    "When fetch_tool_schema succeeds, that tool becomes available on the next step.",
-    "All admin links must be root-relative and start with '/'.",
-    "Build record links as '/resource/{resourceId}/show/{primary key}'. Never use bare 'resource/{resourceId}/show/{primary key}' without the leading slash.",
-    "When the user asks to open or show a page in the AdminForth UI, call navigate_user instead of only sending a link.",
-    "Try to call as many tools as possible in parallel in one step.",
-  ];
-
-  return sections.filter(Boolean).join("\n\n");
-}

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