@adminforth/agent 2.0.10 → 2.2.0

package/agent/models/AgentModelFactory.ts

@@ -1,28 +0,0 @@
-import type { CompletionAdapter } from "adminforth";
-import { createAgentChatModel } from "../simpleAgent.js";
-import type { AgentTurnModels } from "../turn/turnTypes.js";
-
-export class AgentModelFactory {
-  constructor(private readonly maxTokens: number) {}
-
-  async create(completionAdapter: CompletionAdapter): Promise<AgentTurnModels> {
-    const [primaryModelSpec, summaryModelSpec] = await Promise.all([
-      createAgentChatModel({
-        adapter: completionAdapter,
-        maxTokens: this.maxTokens,
-        purpose: "primary",
-      }),
-      createAgentChatModel({
-        adapter: completionAdapter,
-        maxTokens: this.maxTokens,
-        purpose: "summary",
-      }),
-    ]);
-
-    return {
-      model: primaryModelSpec.model,
-      summaryModel: summaryModelSpec.model,
-      modelMiddleware: primaryModelSpec.middleware,
-    };
-  }
-}

package/agent/runtime/AgentContext.ts

@@ -1,30 +0,0 @@
-import type { AdminUser } from "adminforth";
-import { z } from "zod";
-import type { AgentEventEmitter } from "../../agentEvents.js";
-import type { SequenceDebugCollector } from "../middleware/sequenceDebug.js";
-import type { CurrentPageContext } from "../tools/getUserLocation.js";
-import type { AgentTurnContext } from "../turn/turnTypes.js";
-
-export const contextSchema = z.object({
-  adminUser: z.custom<AdminUser>(),
-  userTimeZone: z.string(),
-  sessionId: z.string(),
-  turnId: z.string(),
-  abortSignal: z.custom<AbortSignal>().optional(),
-  currentPage: z.custom<CurrentPageContext>().optional(),
-  chatSurface: z.string().optional(),
-  adminBaseUrl: z.string().optional(),
-  adminPublicOrigin: z.string().optional(),
-  emit: z.custom<AgentEventEmitter>().optional(),
-  sequenceDebugSink: z.custom<SequenceDebugCollector>(),
-});
-
-export function toLangchainAgentContext(
-  context: AgentTurnContext & {
-    adminBaseUrl: string;
-    emit?: AgentEventEmitter;
-    sequenceDebugSink: SequenceDebugCollector;
-  },
-) {
-  return context;
-}

package/agent/runtime/AgentRuntime.ts

@@ -1,89 +0,0 @@
-import type { IAdminForth } from "adminforth";
-import { createAgent, summarizationMiddleware, humanInTheLoopMiddleware } from "langchain";
-import type { BaseCheckpointSaver } from "@langchain/langgraph";
-import { createApiBasedToolsMiddleware } from "../middleware/apiBasedTools.js";
-import { createSequenceDebugMiddleware } from "../middleware/sequenceDebug.js";
-import { createAgentLlmMetricsLogger } from "../simpleAgent.js";
-import type { AgentToolProvider } from "../tools/AgentToolProvider.js";
-import type { AgentRuntimeRunInput } from "../turn/turnTypes.js";
-import { contextSchema, toLangchainAgentContext } from "./AgentContext.js";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
-
-function createHumanInTheLoopInterrupts(
-  apiBasedTools: Record<string, ApiBasedTool>,
-): Record<string, { allowedDecisions: ("approve" | "reject" | "edit")[] }> {
-  return Object.fromEntries(
-    Object.entries(apiBasedTools)
-      .filter(([, apiBasedTool]) => apiBasedTool.agent?.isDangerous === true)
-      .map(([toolName]) => [
-        toolName,
-        {
-          allowedDecisions: ["approve", "reject"],
-        },
-      ]),
-  );
-}
-
-export type AgentRuntimeOptions = {
-  name: string;
-  getAdminforth: () => IAdminForth;
-  getCheckpointer: () => BaseCheckpointSaver;
-  toolProvider: AgentToolProvider;
-};
-
-export class AgentRuntime {
-  constructor(private readonly options: AgentRuntimeOptions) {}
-
-  async stream(input: AgentRuntimeRunInput) {
-    const apiBasedTools = this.options.toolProvider.getApiBasedTools();
-    const tools = await this.options.toolProvider.getTools(apiBasedTools);
-    const adminforth = this.options.getAdminforth();
-    const apiBasedToolsMiddleware = createApiBasedToolsMiddleware(
-      apiBasedTools,
-      adminforth,
-    );
-    const sequenceDebugMiddleware = createSequenceDebugMiddleware(
-      input.observability.sequenceDebugSink,
-    );
-    const hitlMiddleware = humanInTheLoopMiddleware({
-      interruptOn: createHumanInTheLoopInterrupts(apiBasedTools),
-      descriptionPrefix: "Tool execution pending approval",
-    });
-    const middleware = [
-      apiBasedToolsMiddleware,
-      hitlMiddleware,
-      ...(input.models.modelMiddleware ?? []),
-      sequenceDebugMiddleware,
-      summarizationMiddleware({
-        model: input.models.summaryModel,
-        trigger: { tokens: 1024 * 64 },
-        keep: { messages: 10 },
-      }),
-    ] as const;
-
-    const agent = createAgent({
-      name: this.options.name,
-      model: input.models.model,
-      checkpointer: this.options.getCheckpointer(),
-      tools,
-      contextSchema,
-      middleware,
-    });
-
-    return agent.stream(input.input as any, {
-      streamMode: ["messages", "updates"],
-      recursionLimit: 100,
-      callbacks: [createAgentLlmMetricsLogger()],
-      signal: input.context.abortSignal,
-      configurable: {
-        thread_id: input.context.sessionId,
-      },
-      context: toLangchainAgentContext({
-        ...input.context,
-        adminBaseUrl: adminforth.config.baseUrlSlashed,
-        emit: input.observability.emit,
-        sequenceDebugSink: input.observability.sequenceDebugSink,
-      }),
-    });
-  }
-}

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