@adminforth/agent 1.0.0

package/agent/simpleAgent.ts

@@ -0,0 +1,291 @@
+import { createAgent, summarizationMiddleware } from "langchain";
+import { logger, type AdminUser, type CompletionAdapter } from "adminforth";
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import { MemorySaver, type Messages } from "@langchain/langgraph";
+import type { LLMResult } from "@langchain/core/outputs";
+import { z } from "zod";
+import { ChatOpenAI } from "@langchain/openai";
+import { createAgentTools } from "./tools/index.js";
+import { createApiBasedToolsMiddleware } from "./middleware/apiBasedTools.js";
+import {
+  createSequenceDebugMiddleware,
+  type SequenceDebugModelCallSink,
+} from "./middleware/sequenceDebug.js";
+import type { ApiBasedTool } from "../apiBasedTools.js";
+import type { ToolCallEventSink } from "./toolCallEvents.js";
+
+const checkpointer = new MemorySaver();
+
+export const contextSchema = z.object({
+  adminUser: z.custom<AdminUser>(),
+  userTimeZone: z.string(),
+  sessionId: z.string(),
+  turnId: z.string(),
+  emitToolCallEvent: z.custom<ToolCallEventSink>(),
+});
+
+type AgentReasoning =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+
+type OpenAIBackedCompletionAdapter = CompletionAdapter & {
+  options?: {
+    openAiApiKey?: string;
+    model?: string;
+    baseURL?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    extraRequestBodyParameters?: Record<string, unknown>;
+  };
+};
+
+type LlmOutputTokenUsage = {
+  promptTokens?: unknown;
+  completionTokens?: unknown;
+};
+
+type MessageUsageMetadata = {
+  input_tokens?: unknown;
+  output_tokens?: unknown;
+};
+
+type PendingLlmRun = {
+  startedAt: number;
+  firstTokenAt?: number;
+};
+
+function getFiniteNumber(value: unknown) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function extractTokenUsage(output: LLMResult) {
+  const llmOutputTokenUsage = (
+    output.llmOutput as { tokenUsage?: LlmOutputTokenUsage } | undefined
+  )?.tokenUsage;
+
+  const promptTokens = getFiniteNumber(llmOutputTokenUsage?.promptTokens);
+  const completionTokens = getFiniteNumber(
+    llmOutputTokenUsage?.completionTokens,
+  );
+
+  if (promptTokens !== undefined || completionTokens !== undefined) {
+    return {
+      InputTokens: promptTokens ?? 0,
+      outputTokens: completionTokens ?? 0,
+    };
+  }
+
+  let InputTokens = 0;
+  let outputTokens = 0;
+
+  for (const generationBatch of output.generations) {
+    for (const generation of generationBatch) {
+      if (!("message" in generation) || !generation.message) {
+        continue;
+      }
+
+      const message = generation.message as {
+        usage_metadata?: MessageUsageMetadata;
+        response_metadata?: {
+          tokenUsage?: LlmOutputTokenUsage;
+        };
+      };
+
+      InputTokens +=
+        getFiniteNumber(message.usage_metadata?.input_tokens) ??
+        getFiniteNumber(message.response_metadata?.tokenUsage?.promptTokens) ??
+        0;
+      outputTokens +=
+        getFiniteNumber(message.usage_metadata?.output_tokens) ??
+        getFiniteNumber(
+          message.response_metadata?.tokenUsage?.completionTokens,
+        ) ??
+        0;
+    }
+  }
+
+  return { InputTokens, outputTokens };
+}
+
+class AgentLlmMetricsLogger extends BaseCallbackHandler {
+  name = "AgentLlmMetricsLogger";
+  lc_prefer_streaming = true;
+
+  private readonly pendingRuns = new Map<string, PendingLlmRun>();
+
+  async handleLLMStart(_llm: unknown, _prompts: string[], runId: string) {
+    this.pendingRuns.set(runId, { startedAt: Date.now() });
+  }
+
+  async handleLLMNewToken(
+    _token: string,
+    _chunk: unknown,
+    runId: string,
+  ) {
+    const pendingRun = this.pendingRuns.get(runId);
+
+    if (!pendingRun || pendingRun.firstTokenAt !== undefined) {
+      return;
+    }
+
+    pendingRun.firstTokenAt = Date.now();
+  }
+
+  async handleLLMEnd(output: LLMResult, runId: string) {
+    const pendingRun = this.pendingRuns.get(runId);
+
+    if (!pendingRun) {
+      return;
+    }
+
+    this.pendingRuns.delete(runId);
+
+    const finishedAt = Date.now();
+    const rtt = finishedAt - pendingRun.startedAt;
+    const ttft =
+      pendingRun.firstTokenAt === undefined
+        ? rtt
+        : pendingRun.firstTokenAt - pendingRun.startedAt;
+    const { InputTokens, outputTokens } = extractTokenUsage(output);
+
+    logger.info(
+      { InputTokens, outputTokens, ttft, rtt },
+      "LLM call finished",
+    );
+  }
+
+  async handleLLMError(_error: unknown, runId: string) {
+    this.pendingRuns.delete(runId);
+  }
+}
+
+function createAgentLlmMetricsLogger() {
+  return new AgentLlmMetricsLogger();
+}
+
+function normalizeReasoning(reasoning: AgentReasoning) {
+  if (reasoning === "none") {
+    return undefined;
+  }
+
+  return {
+    effort: reasoning as "minimal" | "low" | "medium" | "high" | "xhigh",
+    summary: "auto" as const,
+  };
+}
+
+export function createAgentChatModel(params: {
+  adapter: CompletionAdapter;
+  maxTokens: number;
+  reasoning: AgentReasoning;
+  modelName?: string;
+}) {
+  const adapter = params.adapter as OpenAIBackedCompletionAdapter;
+  const options = adapter.options ?? {};
+
+  if (!options.openAiApiKey) {
+    throw new Error(
+      "CompletionAdapter must expose options.openAiApiKey for ChatOpenAI",
+    );
+  }
+
+  const model = params.modelName ?? options.model ?? "gpt-5-nano";
+  const baseURL = options.baseURL ?? options.baseUrl;
+  const reasoning = normalizeReasoning(params.reasoning);
+
+  return new ChatOpenAI({
+    apiKey: options.openAiApiKey,
+    model,
+    maxTokens: params.maxTokens,
+    useResponsesApi: true,
+    outputVersion: "v1",
+    ...(reasoning ? { reasoning } : {}),
+    ...(typeof options.timeoutMs === "number"
+      ? { timeout: options.timeoutMs }
+      : {}),
+    ...(baseURL
+      ? {
+          configuration: {
+            baseURL,
+          },
+        }
+      : {}),
+  });
+}
+
+export async function callAgent(params: {
+  name: string;
+  model: ChatOpenAI;
+  summaryModel: ChatOpenAI;
+  messages: Messages;
+  adminUser: AdminUser;
+  apiBasedTools: Record<string, ApiBasedTool>;
+  customComponentsDir: string;
+  sessionId: string;
+  turnId: string;
+  userTimeZone: string;
+  emitToolCallEvent: ToolCallEventSink;
+  sequenceDebugSink: SequenceDebugModelCallSink;
+}) {
+  const {
+    name,
+    model,
+    summaryModel,
+    messages,
+    adminUser,
+    apiBasedTools,
+    customComponentsDir,
+    sessionId,
+    turnId,
+    userTimeZone,
+    emitToolCallEvent,
+    sequenceDebugSink,
+  } = params;
+
+  const tools = await createAgentTools(customComponentsDir, apiBasedTools);
+  const apiBasedToolsMiddleware = createApiBasedToolsMiddleware(apiBasedTools);
+  const sequenceDebugMiddleware = createSequenceDebugMiddleware(
+    sequenceDebugSink,
+  );
+
+  const middleware = [
+    apiBasedToolsMiddleware,
+    sequenceDebugMiddleware,
+    summarizationMiddleware({
+      model: summaryModel,
+      trigger: { tokens: 1024 * 8 },
+      keep: { messages: 10 },
+    }),
+  ] as const;
+
+  const agent = createAgent<undefined, typeof contextSchema, typeof middleware>({
+    name,
+    model,
+    checkpointer,
+    tools,
+    contextSchema,
+    middleware,
+  });
+
+  return await agent.stream({ messages } as any, {
+    streamMode: "messages",
+    recursionLimit: 50,
+    callbacks: [createAgentLlmMetricsLogger()],
+    configurable: {
+      thread_id: sessionId,
+    },
+    context: {
+      adminUser,
+      userTimeZone,
+      sessionId,
+      turnId,
+      emitToolCallEvent,
+    },
+  });
+}

package/agent/skills/registry.ts

@@ -0,0 +1,135 @@
+import { readdir, readFile } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { parse as parseYaml } from "yaml";
+
+const PLUGIN_SKILLS_DIRECTORY_PATH = fileURLToPath(
+  new URL("../../custom/skills/", import.meta.url),
+);
+const SKILL_MARKDOWN_FILENAME = "SKILL.md";
+const SKILL_FRONTMATTER_SEPARATOR = "\n---\n";
+
+export interface AgentSkillManifest {
+  directoryName: string;
+  name: string;
+  description: string;
+  instructions: string;
+}
+
+function parseSkillManifest(directoryName: string, markdown: string): AgentSkillManifest {
+  const [frontmatterBlock, instructions = ""] = markdown.split("\r\n").join("\n").split(
+    SKILL_FRONTMATTER_SEPARATOR,
+    2,
+  );
+  const metadata = parseYaml(frontmatterBlock) as {
+    name?: string;
+    description?: string;
+  };
+
+  return {
+    directoryName,
+    name: metadata.name ?? directoryName,
+    description: metadata.description ?? "",
+    instructions: instructions.trim(),
+  };
+}
+
+async function readSkillManifest(skillsDirectoryPath: string, directoryName: string) {
+  const markdown = await readFile(
+    path.join(skillsDirectoryPath, directoryName, SKILL_MARKDOWN_FILENAME),
+    "utf8",
+  );
+
+  return parseSkillManifest(directoryName, markdown);
+}
+
+async function listDirectorySkillManifests(skillsDirectoryPath: string) {
+  try {
+    const entries = await readdir(skillsDirectoryPath, { withFileTypes: true });
+
+    return await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+        .map((directoryName) => readSkillManifest(skillsDirectoryPath, directoryName)),
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+}
+
+function mergeSkillManifests(skillGroups: AgentSkillManifest[][]) {
+  return Array.from(
+    new Map(
+      skillGroups.flat().map((skill) => [
+        `${skill.name}:${skill.directoryName}`,
+        skill,
+      ]),
+    ).values(),
+  );
+}
+
+export function getProjectSkillsDirectoryPath(customComponentsDir: string) {
+  return path.resolve(customComponentsDir, "skills");
+}
+
+export async function listBundledSkillManifests() {
+  return await listDirectorySkillManifests(PLUGIN_SKILLS_DIRECTORY_PATH);
+}
+
+export async function listProjectSkillManifests(customComponentsDir: string) {
+  return await listDirectorySkillManifests(
+    getProjectSkillsDirectoryPath(customComponentsDir),
+  );
+}
+
+export async function listSkillManifests(customComponentsDir: string) {
+  return mergeSkillManifests([
+    await listProjectSkillManifests(customComponentsDir),
+    await listBundledSkillManifests(),
+  ]);
+}
+
+export async function loadSkillManifest(skillName: string, customComponentsDir: string) {
+  const manifests = await listSkillManifests(customComponentsDir);
+
+  return (
+    manifests.find(
+      (manifest) =>
+        manifest.name === skillName || manifest.directoryName === skillName,
+    ) ?? null
+  );
+}
+
+export async function loadSkillMarkdown(skillName: string, customComponentsDir: string) {
+  const manifest = await loadSkillManifest(skillName, customComponentsDir);
+
+  if (!manifest) {
+    return null;
+  }
+
+  const directories = [
+    getProjectSkillsDirectoryPath(customComponentsDir),
+    PLUGIN_SKILLS_DIRECTORY_PATH,
+  ];
+
+  for (const skillsDirectoryPath of directories) {
+    try {
+      return await readFile(
+        path.join(skillsDirectoryPath, manifest.directoryName, SKILL_MARKDOWN_FILENAME),
+        "utf8",
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+
+  return null;
+}

package/agent/systemPrompt.ts

@@ -0,0 +1,69 @@
+import type { AdminForthResource, IAdminForth } from "adminforth";
+import {
+  listBundledSkillManifests,
+  listProjectSkillManifests,
+  type AgentSkillManifest,
+} from "./skills/registry.js";
+import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "./tools/index.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",
+
+  
+].join(" ");
+
+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) {
+  const [primarySkills, defaultSkills] = await Promise.all([
+    listProjectSkillManifests(adminforth.config.customization.customComponentsDir),
+    listBundledSkillManifests(),
+  ]);
+  const alwaysAvailableTools = ALWAYS_AVAILABLE_API_TOOL_NAMES.join(", ");
+  const sections = [
+    DEFAULT_AGENT_SYSTEM_PROMPT,
+    `BASE_URL: ${adminforth.config.baseUrl}`,
+    `List of resources:\n${formatResources(adminforth.config.resources)}`,
+    `You have always-available base tools: ${alwaysAvailableTools}.`,
+    primarySkills.length > 0
+      ? `You have primary skills set:\n${formatSkills(primarySkills, "skill_name")}`
+      : "",
+    "You have next default skills which you can fallback to if primary skill set does not provide a good skill:\n" +
+      formatSkills(defaultSkills, "skill_name"),
+    "Before using any skill, call fetch_skill to load its full instructions.",
+    "You can use get_resource immediately to inspect resource structure and column names.",
+    "Only call fetch_tool_schema for tool names that are explicitly mentioned in a fetched skill and are not already available as base tools.",
+    "When fetch_tool_schema succeeds, that tool becomes available on the next step.",
+    "Try to call as many tools as possible in parallel in one step.",
+  ];
+
+  return sections.filter(Boolean).join("\n\n");
+}

package/agent/toolCallEvents.ts

@@ -0,0 +1,17 @@
+export type ToolCallEvent =
+  | {
+      toolCallId: string;
+      toolName: 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;

package/agent/tools/apiTool.ts

@@ -0,0 +1,99 @@
+import { tool } from "langchain";
+import { randomUUID } from "crypto";
+import YAML from "yaml";
+import type { ApiBasedTool } from "../../apiBasedTools.js";
+import { serializeUnknownError } 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>;
+      const toolCallId = randomUUID();
+      const startedAt = Date.now();
+      runtime.context.emitToolCallEvent({
+        toolCallId,
+        toolName,
+        phase: "start",
+        input: YAML.stringify(normalizedInput),
+      });
+
+      try {
+        const output = await apiBasedTool.call({
+          adminUser: runtime.context.adminUser,
+          inputs: normalizedInput,
+          userTimeZone: runtime.context.userTimeZone,
+        });
+
+        runtime.context.emitToolCallEvent({
+          toolCallId,
+          toolName,
+          phase: "end",
+          durationMs: Date.now() - startedAt,
+          output,
+          error: null,
+        });
+
+        return output;
+      } catch (error) {
+        runtime.context.emitToolCallEvent({
+          toolCallId,
+          toolName,
+          phase: "end",
+          durationMs: Date.now() - startedAt,
+          output: null,
+          error: YAML.stringify(serializeUnknownError(error)),
+        });
+        throw error;
+      }
+    },
+    {
+      name: toolName,
+      description: apiBasedTool.description ?? `${toolName} tool`,
+      schema: normalizeToolInputSchema(apiBasedTool.input_schema),
+    },
+  );
+}

package/agent/tools/fetchSkill.ts

@@ -0,0 +1,58 @@
+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) {
+  const availableSkills = await listSkillManifests(customComponentsDir);
+  const availableSkillNames = availableSkills.map((skill) => skill.name);
+
+  return tool(
+    async ({ skillName }) => {
+      try {
+        const skillMarkdown = await loadSkillMarkdown(skillName, customComponentsDir);
+
+        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,
+    },
+  );
+}