@adminforth/agent 2.0.10 → 2.1.0

package/agent/simpleAgent.ts

@@ -1,199 +0,0 @@
-import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
-import {
-  logger,
-  type CompletionAdapter,
-} from "adminforth";
-import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
-import type { LLMResult } from "@langchain/core/outputs";
-import {
-  createSequenceDebugMiddleware,
-} from "./middleware/sequenceDebug.js";
-
-export type AgentChatModel = BaseChatModel<any, any>;
-export type AgentModelPurpose = "primary" | "summary";
-export type AgentModeCompletionAdapter = CompletionAdapter & {
-  getLangChainAgentSpec(params: {
-    maxTokens: number;
-    purpose: AgentModelPurpose;
-  }): Promise<{
-    model: unknown;
-    middleware?: unknown[];
-  }> | {
-    model: unknown;
-    middleware?: unknown[];
-  };
-};
-
-export type AgentMiddleware = ReturnType<typeof createSequenceDebugMiddleware>;
-
-type AgentChatModelSpec = {
-  model: AgentChatModel;
-  middleware: AgentMiddleware[];
-};
-
-type LlmOutputTokenUsage = {
-  promptTokens?: unknown;
-  completionTokens?: unknown;
-};
-
-type MessageUsageMetadata = {
-  input_tokens?: unknown;
-  output_tokens?: unknown;
-};
-
-type PendingLlmRun = {
-  startedAt: number;
-  firstTokenAt?: number;
-};
-
-function isLangChainAgentCompletionAdapter(
-  adapter: CompletionAdapter,
-): adapter is AgentModeCompletionAdapter {
-  return typeof (adapter as AgentModeCompletionAdapter)
-    .getLangChainAgentSpec === "function";
-}
-
-async function getAgentChatModelSpec(params: {
-  adapter: AgentModeCompletionAdapter;
-  maxTokens: number;
-  purpose: AgentModelPurpose;
-}): Promise<AgentChatModelSpec> {
-  const spec = await params.adapter.getLangChainAgentSpec({
-    maxTokens: params.maxTokens,
-    purpose: params.purpose,
-  });
-
-  return {
-    model: spec.model as AgentChatModel,
-    middleware: (spec.middleware ?? []) as AgentMiddleware[],
-  };
-}
-
-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);
-  }
-}
-
-export function createAgentLlmMetricsLogger() {
-  return new AgentLlmMetricsLogger();
-}
-
-export async function createAgentChatModel(params: {
-  adapter: CompletionAdapter;
-  maxTokens: number;
-  purpose: AgentModelPurpose;
-}) {
-  if (!isLangChainAgentCompletionAdapter(params.adapter)) {
-    throw new Error(
-      "AdminForth Agent requires completionAdapter to implement getLangChainAgentSpec({ maxTokens, purpose }).",
-    );
-  }
-
-  return await getAgentChatModelSpec({
-    adapter: params.adapter,
-    maxTokens: params.maxTokens,
-    purpose: params.purpose,
-  });
-}

package/agent/skills/registry.ts

@@ -1,162 +0,0 @@
-import { readdir, readFile } from "fs/promises";
-import path from "path";
-import { parse as parseYaml } from "yaml";
-
-const SKILL_MARKDOWN_FILENAME = "SKILL.md";
-const SKILL_FRONTMATTER_SEPARATOR = "\n---\n";
-
-export interface AgentSkillManifest {
-  directoryName: string;
-  name: string;
-  description: string;
-  instructions: string;
-}
-
-function normalizePluginSkillDirectoryPaths(pluginCustomFolderPaths: string[] = []) {
-  return Array.from(new Set(
-    pluginCustomFolderPaths
-      .map((pluginCustomFolderPath) => path.resolve(pluginCustomFolderPath, "skills")),
-  ));
-}
-
-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");
-}
-
-function getProjectSkillDirectoryPaths(
-  customComponentsDir: string,
-  pluginCustomFolderPaths: string[] = [],
-) {
-  return Array.from(new Set([
-    getProjectSkillsDirectoryPath(customComponentsDir),
-    ...normalizePluginSkillDirectoryPaths(pluginCustomFolderPaths),
-  ]));
-}
-
-export async function listProjectSkillManifests(
-  customComponentsDir: string,
-  pluginCustomFolderPaths: string[] = [],
-) {
-  return mergeSkillManifests(
-    await Promise.all(
-      getProjectSkillDirectoryPaths(customComponentsDir, pluginCustomFolderPaths).map(
-        listDirectorySkillManifests,
-      ),
-    ),
-  );
-}
-
-export async function listSkillManifests(
-  customComponentsDir: string,
-  pluginCustomFolderPaths: string[] = [],
-) {
-  return await listProjectSkillManifests(customComponentsDir, pluginCustomFolderPaths);
-}
-
-export async function loadSkillManifest(
-  skillName: string,
-  customComponentsDir: string,
-  pluginCustomFolderPaths: string[] = [],
-) {
-  const manifests = await listSkillManifests(customComponentsDir, pluginCustomFolderPaths);
-
-  return (
-    manifests.find(
-      (manifest) =>
-        manifest.name === skillName || manifest.directoryName === skillName,
-    ) ?? null
-  );
-}
-
-export async function loadSkillMarkdown(
-  skillName: string,
-  customComponentsDir: string,
-  pluginCustomFolderPaths: string[] = [],
-) {
-  const manifest = await loadSkillManifest(
-    skillName,
-    customComponentsDir,
-    pluginCustomFolderPaths,
-  );
-
-  if (!manifest) {
-    return null;
-  }
-
-  const directories = [
-    ...getProjectSkillDirectoryPaths(customComponentsDir, pluginCustomFolderPaths),
-  ];
-
-  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/speech/SpeechTurnService.ts

@@ -1,179 +0,0 @@
-import { logger } from "adminforth";
-import { getErrorMessage, isAbortError } from "../../errors.js";
-import { sanitizeSpeechText } from "../../sanitizeSpeechText.js";
-import type {
-  RunAndPersistAgentResponseInput,
-  RunAndPersistAgentResponseResult,
-  SpeechAgentTurnInput,
-} from "../turn/turnTypes.js";
-
-export class SpeechTurnService {
-  constructor(
-    private readonly runAndPersistAgentResponse: (
-      input: RunAndPersistAgentResponseInput,
-    ) => Promise<RunAndPersistAgentResponseResult>,
-  ) {}
-
-  async handle(input: SpeechAgentTurnInput) {
-    let transcription;
-
-    try {
-      transcription = await input.audioAdapter.transcribe({
-        buffer: input.audio.buffer,
-        filename: input.audio.filename,
-        mimeType: input.audio.mimeType,
-        language: "auto",
-        abortSignal: input.abortSignal,
-      });
-    } catch (error) {
-      if (input.abortSignal?.aborted || isAbortError(error)) {
-        logger.info("Agent speech transcription aborted by the client");
-        await input.emit({ type: "finish" });
-        return null;
-      }
-
-      logger.error(`Agent speech transcription failed:\n${getErrorMessage(error)}`);
-      await input.emit({
-        type: "error",
-        error: "Speech transcription failed. Check server logs for details.",
-      });
-      await input.emit({ type: "finish" });
-      return null;
-    }
-
-    if (input.abortSignal?.aborted) {
-      await input.emit({ type: "finish" });
-      return null;
-    }
-
-    const prompt = transcription.text;
-    if (!prompt) {
-      await input.emit({
-        type: "error",
-        error: "Speech transcription is empty",
-      });
-      await input.emit({ type: "finish" });
-      return null;
-    }
-
-    await input.emit({
-      type: "transcript",
-      text: transcription.text,
-      language: transcription.language,
-    });
-
-    const agentResponse = await this.runAndPersistAgentResponse({
-      prompt,
-      sessionId: input.sessionId,
-      modeName: input.modeName,
-      userTimeZone: input.userTimeZone,
-      currentPage: input.currentPage,
-      chatSurface: input.chatSurface,
-      adminPublicOrigin: input.adminPublicOrigin,
-      abortSignal: input.abortSignal,
-      adminUser: input.adminUser,
-      emit: async (event) => {
-        if (event.type === "tool-call") {
-          await input.emit(event);
-        }
-      },
-      failureLogMessage: input.failureLogMessage ?? "Agent speech response failed",
-      abortLogMessage: input.abortLogMessage ?? "Agent speech response aborted by the client",
-    });
-
-    if (agentResponse.aborted) {
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    }
-
-    if (agentResponse.failed) {
-      await input.emit({
-        type: "error",
-        error: agentResponse.text,
-      });
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    }
-
-    try {
-      await input.emit({
-        type: "speech-response",
-        transcript: {
-          text: transcription.text,
-          language: transcription.language,
-        },
-        response: {
-          text: agentResponse.text,
-        },
-        sessionId: input.sessionId,
-        turnId: agentResponse.turnId,
-      });
-      const speech = await input.audioAdapter.synthesize({
-        text: sanitizeSpeechText(agentResponse.text),
-        stream: true,
-        streamFormat: "audio",
-        format: "pcm",
-        abortSignal: input.abortSignal,
-      });
-
-      await input.emit({
-        type: "audio-start",
-        mimeType: speech.mimeType,
-        format: speech.format,
-        sampleRate: 24000,
-        channelCount: 1,
-        bitsPerSample: 16,
-      });
-
-      const reader = speech.audioStream.getReader();
-      const cancelAudioStream = () => {
-        void reader.cancel().catch(() => undefined);
-      };
-
-      try {
-        input.abortSignal?.addEventListener("abort", cancelAudioStream, { once: true });
-
-        while (true) {
-          if (input.abortSignal?.aborted) {
-            await reader.cancel().catch(() => undefined);
-            break;
-          }
-
-          const { value, done } = await reader.read();
-
-          if (done) {
-            break;
-          }
-
-          if (input.abortSignal?.aborted) {
-            break;
-          }
-
-          await input.emit({
-            type: "audio-delta",
-            value,
-          });
-        }
-      } finally {
-        input.abortSignal?.removeEventListener("abort", cancelAudioStream);
-        reader.releaseLock();
-      }
-
-      await input.emit({ type: "audio-done" });
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    } catch (error) {
-      if (input.abortSignal?.aborted || isAbortError(error)) {
-        logger.info("Agent speech audio streaming aborted by the client");
-      } else {
-        logger.error(`Agent speech audio streaming failed:\n${getErrorMessage(error)}`);
-        await input.emit({
-          type: "error",
-          error: getErrorMessage(error),
-        });
-      }
-      await input.emit({ type: "finish" });
-      return agentResponse;
-    }
-  }
-}

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");
-}