@adminforth/agent 2.0.10 → 2.1.0

package/agent/middleware/sequenceDebug.ts

@@ -1,429 +0,0 @@
-import { AIMessage } from "@langchain/core/messages";
-import { createMiddleware } from "langchain";
-import YAML from "yaml";
-import type { ToolCallEvent } from "../toolCallEvents.js";
-
-export type SequenceDebugResultType = "tool_calls" | "final_text";
-
-type SequenceDebugToolCall = {
-  toolCallId: string;
-  toolName: string;
-  input: string;
-  output: string | null;
-  error: string | null;
-};
-
-type PendingSequenceDebugToolCall = SequenceDebugToolCall & {
-  completed: boolean;
-};
-
-export type SequenceDebug = {
-  sequenceId: number;
-  startedAt: string;
-  prompt: string;
-  promptTokens: number;
-  reasoning: string;
-  reasoningTokens: number;
-  text: string;
-  textTokens: number;
-  uncachedInputTokens: number;
-  cachedInputTokens: number;
-  outputTokens: number;
-  cachedTokens: number;
-  responseId: string | null;
-  toolCalls: SequenceDebugToolCall[];
-  endedAt: string;
-  resultType: SequenceDebugResultType;
-};
-
-type PendingSequenceDebug = Omit<SequenceDebug, "toolCalls" | "endedAt" | "resultType"> & {
-  toolCalls: PendingSequenceDebugToolCall[];
-  pendingToolCalls: number;
-  resultType: SequenceDebugResultType | null;
-};
-
-type SequenceDebugModelCall = {
-  promptTokens: number;
-  reasoning: string;
-  reasoningTokens: number;
-  text: string;
-  textTokens: number;
-  uncachedInputTokens: number;
-  cachedInputTokens: number;
-  outputTokens: number;
-  cachedTokens: number;
-  responseId: string | null;
-  resultType: SequenceDebugResultType;
-};
-
-type OpenAiUsageMetadata = {
-  input_tokens?: number;
-  output_tokens?: number;
-  input_token_details?: {
-    cache_read?: number;
-  };
-};
-
-type OpenAiResponseMetadata = {
-  id?: string;
-};
-
-export type SequenceDebugModelCallSink = {
-  handleModelCallStart: (prompt: string) => void;
-  handleModelCallComplete: (params: SequenceDebugModelCall) => void;
-};
-
-export type SequenceDebugCollector = SequenceDebugModelCallSink & {
-  handleToolCallEvent: (event: ToolCallEvent) => void;
-  flush: () => void;
-  getHistory: () => SequenceDebug[];
-};
-
-function createPendingSequenceDebug(sequenceId: number): PendingSequenceDebug {
-  return {
-    sequenceId,
-    startedAt: new Date().toISOString(),
-    prompt: "",
-    promptTokens: 0,
-    reasoning: "",
-    reasoningTokens: 0,
-    text: "",
-    textTokens: 0,
-    uncachedInputTokens: 0,
-    cachedInputTokens: 0,
-    outputTokens: 0,
-    cachedTokens: 0,
-    responseId: null,
-    toolCalls: [],
-    pendingToolCalls: 0,
-    resultType: null,
-  };
-}
-
-function hasSequenceDebugContent(sequence: PendingSequenceDebug | null): sequence is PendingSequenceDebug {
-  return Boolean(
-    sequence &&
-      (
-        sequence.prompt ||
-        sequence.reasoning ||
-        sequence.text ||
-        sequence.toolCalls.length > 0
-      ),
-  );
-}
-
-function finalizeSequenceDebug(sequence: PendingSequenceDebug): SequenceDebug {
-  return {
-    sequenceId: sequence.sequenceId,
-    startedAt: sequence.startedAt,
-    prompt: sequence.prompt,
-    promptTokens: sequence.promptTokens,
-    reasoning: sequence.reasoning,
-    reasoningTokens: sequence.reasoningTokens,
-    text: sequence.text,
-    textTokens: sequence.textTokens,
-    uncachedInputTokens: sequence.uncachedInputTokens,
-    cachedInputTokens: sequence.cachedInputTokens,
-    outputTokens: sequence.outputTokens,
-    cachedTokens: sequence.cachedTokens,
-    responseId: sequence.responseId,
-    toolCalls: sequence.toolCalls.map(({ completed: _completed, ...toolCall }) => toolCall),
-    endedAt: new Date().toISOString(),
-    resultType: sequence.resultType ?? "final_text",
-  };
-}
-
-type SequenceDebugPromptModel = {
-  getName?: () => string;
-  model?: string;
-  _defaultConfig?: {
-    modelProvider?: string;
-  };
-  invocationParams?: (options?: Record<string, unknown>) => Record<string, unknown>;
-};
-
-function getDebugModelName(model: SequenceDebugPromptModel) {
-  return typeof model.getName === "function" ? model.getName() : undefined;
-}
-
-function getDebugToolName(tool: unknown) {
-  if (!tool || typeof tool !== "object") {
-    return null;
-  }
-
-  const name = (tool as { name?: unknown }).name;
-  return typeof name === "string" ? name : null;
-}
-
-function formatToolsForDebug(tools: unknown[]) {
-  return tools.map((tool) => ({
-    name: getDebugToolName(tool),
-  }));
-}
-
-function stringifyPromptForDebug(params: {
-  model: SequenceDebugPromptModel;
-  systemMessage: { text: string };
-  messages: unknown[];
-  tools: unknown[];
-  toolChoice?: unknown;
-  modelSettings?: Record<string, unknown>;
-}) {
-  const { model, systemMessage, messages, tools, toolChoice, modelSettings } = params;
-  const invocationParams =
-    typeof model.invocationParams === "function"
-      ? model.invocationParams({
-          ...(modelSettings ?? {}),
-          ...(tools.length > 0 ? { tools } : {}),
-          ...(toolChoice !== undefined ? { tool_choice: toolChoice } : {}),
-        })
-      : null;
-
-  return YAML.stringify({
-    model: {
-      name: getDebugModelName(model) ?? null,
-      provider: model._defaultConfig?.modelProvider ?? null,
-      configuredModel:
-        typeof model.model === "string" ? model.model : null,
-    },
-    systemMessage,
-    messages,
-    ...(tools.length > 0 ? { tools: formatToolsForDebug(tools) } : {}),
-    ...(toolChoice !== undefined ? { toolChoice } : {}),
-    ...(modelSettings ? { modelSettings } : {}),
-    ...(invocationParams ? { invocationParams } : {}),
-  });
-}
-
-function getMessageBlocks(message: {
-  contentBlocks?: unknown;
-  content?: unknown;
-}) {
-  if (Array.isArray(message.contentBlocks)) {
-    return message.contentBlocks;
-  }
-
-  if (Array.isArray(message.content)) {
-    return message.content;
-  }
-
-  return [];
-}
-
-function hasToolCallSignal(message: {
-  tool_calls?: unknown;
-  tool_call_chunks?: unknown;
-  additional_kwargs?: { tool_calls?: unknown };
-}) {
-  return Boolean(
-    (Array.isArray(message.tool_calls) && message.tool_calls.length > 0) ||
-      (Array.isArray(message.tool_call_chunks) && message.tool_call_chunks.length > 0) ||
-      (Array.isArray(message.additional_kwargs?.tool_calls) &&
-        message.additional_kwargs.tool_calls.length > 0),
-  );
-}
-
-function hasTokenCounter(model: unknown): model is {
-  getNumTokens: (content: string) => Promise<number>;
-} {
-  return (
-    typeof model === "object" &&
-    model !== null &&
-    "getNumTokens" in model &&
-    typeof model.getNumTokens === "function"
-  );
-}
-
-async function countTokens(model: unknown, content: string) {
-  if (!content) {
-    return 0;
-  }
-
-  if (!hasTokenCounter(model)) {
-    return 0;
-  }
-
-  return await model.getNumTokens(content);
-}
-
-function extractSequenceResponseDebug(message: AIMessage): SequenceDebugModelCall {
-  const usageMetadata = message.usage_metadata as OpenAiUsageMetadata | undefined;
-  const promptTokens = usageMetadata?.input_tokens ?? 0;
-  const cachedInputTokens = usageMetadata?.input_token_details?.cache_read ?? 0;
-  const blocks = getMessageBlocks(message);
-  const reasoning = blocks
-    .filter((block: any) => block?.type === "reasoning")
-    .map((block: any) => String(block.reasoning ?? ""))
-    .join("");
-  const textFromBlocks = blocks
-    .filter((block: any) => block?.type === "text")
-    .map((block: any) => String(block.text ?? ""))
-    .join("");
-
-  return {
-    promptTokens,
-    reasoning,
-    reasoningTokens: 0,
-    text: textFromBlocks || (typeof message.content === "string" ? message.content : ""),
-    textTokens: 0,
-    uncachedInputTokens: Math.max(promptTokens - cachedInputTokens, 0),
-    cachedInputTokens,
-    outputTokens: usageMetadata?.output_tokens ?? 0,
-    cachedTokens: cachedInputTokens,
-    responseId:
-      (message.response_metadata as OpenAiResponseMetadata | undefined)?.id ??
-      null,
-    resultType: hasToolCallSignal(message) ? "tool_calls" : "final_text",
-  };
-}
-
-export function createSequenceDebugCollector(): SequenceDebugCollector {
-  let nextSequenceId = 1;
-  let currentSequenceDebug: PendingSequenceDebug | null = null;
-  const history: SequenceDebug[] = [];
-
-  const ensureSequenceDebug = () => {
-    if (!currentSequenceDebug) {
-      currentSequenceDebug = createPendingSequenceDebug(nextSequenceId++);
-    }
-
-    return currentSequenceDebug;
-  };
-
-  const flush = () => {
-    if (!hasSequenceDebugContent(currentSequenceDebug)) {
-      currentSequenceDebug = null;
-      return;
-    }
-
-    const finalizedSequenceDebug = finalizeSequenceDebug(currentSequenceDebug);
-    history.push(finalizedSequenceDebug);
-    currentSequenceDebug = null;
-  };
-
-  return {
-    handleModelCallStart(prompt) {
-      if (
-        currentSequenceDebug?.resultType &&
-        currentSequenceDebug.pendingToolCalls === 0
-      ) {
-        flush();
-      }
-
-      const sequenceDebug = ensureSequenceDebug();
-      sequenceDebug.prompt = prompt;
-    },
-    handleModelCallComplete(params) {
-      const sequenceDebug = ensureSequenceDebug();
-      sequenceDebug.promptTokens = params.promptTokens;
-      sequenceDebug.reasoning = params.reasoning;
-      sequenceDebug.reasoningTokens = params.reasoningTokens;
-      sequenceDebug.text = params.text;
-      sequenceDebug.textTokens = params.textTokens;
-      sequenceDebug.uncachedInputTokens = params.uncachedInputTokens;
-      sequenceDebug.cachedInputTokens = params.cachedInputTokens;
-      sequenceDebug.outputTokens = params.outputTokens;
-      sequenceDebug.cachedTokens = params.cachedTokens;
-      sequenceDebug.responseId = params.responseId;
-      sequenceDebug.resultType = params.resultType;
-
-      if (
-        sequenceDebug.resultType === "final_text" &&
-        sequenceDebug.pendingToolCalls === 0
-      ) {
-        flush();
-      }
-    },
-    handleToolCallEvent(event) {
-      const sequenceDebug = ensureSequenceDebug();
-
-      if (event.phase === "start") {
-        sequenceDebug.toolCalls.push({
-          toolCallId: event.toolCallId,
-          toolName: event.toolName,
-          input: event.input,
-          output: null,
-          error: null,
-          completed: false,
-        });
-        sequenceDebug.pendingToolCalls += 1;
-        return;
-      }
-
-      const pendingToolCall = sequenceDebug.toolCalls.find(
-        (toolCall) => toolCall.toolCallId === event.toolCallId && !toolCall.completed,
-      );
-
-      if (pendingToolCall) {
-        pendingToolCall.output = event.output;
-        pendingToolCall.error = event.error;
-        pendingToolCall.completed = true;
-      } else {
-        sequenceDebug.toolCalls.push({
-          toolCallId: event.toolCallId,
-          toolName: event.toolName,
-          input: "",
-          output: event.output,
-          error: event.error,
-          completed: true,
-        });
-      }
-
-      sequenceDebug.pendingToolCalls = Math.max(
-        0,
-        sequenceDebug.pendingToolCalls - 1,
-      );
-
-      if (
-        sequenceDebug.resultType === "tool_calls" &&
-        sequenceDebug.pendingToolCalls === 0
-      ) {
-        flush();
-      }
-    },
-    flush,
-    getHistory() {
-      return history;
-    },
-  };
-}
-
-export function createSequenceDebugMiddleware(
-  sink: SequenceDebugModelCallSink,
-) {
-  return createMiddleware({
-    name: "SequenceDebugMiddleware",
-    async wrapModelCall(request, handler) {
-      const prompt = stringifyPromptForDebug({
-        model: request.model as unknown as SequenceDebugPromptModel,
-        systemMessage: request.systemMessage,
-        messages: request.messages,
-        tools: request.tools,
-        toolChoice: request.toolChoice,
-        modelSettings: request.modelSettings,
-      });
-
-      sink.handleModelCallStart(
-        prompt,
-      );
-
-      const response = await handler(request) as AIMessage;
-      const debug = extractSequenceResponseDebug(response);
-      const [promptTokens, reasoningTokens, textTokens] = await Promise.all([
-        debug.promptTokens || countTokens(request.model, prompt),
-        countTokens(request.model, debug.reasoning),
-        countTokens(request.model, debug.text),
-      ]);
-
-      sink.handleModelCallComplete({
-        ...debug,
-        promptTokens,
-        reasoningTokens,
-        textTokens,
-        uncachedInputTokens: debug.promptTokens ? debug.uncachedInputTokens : promptTokens,
-        outputTokens: debug.outputTokens || reasoningTokens + textTokens,
-      });
-      return response;
-    },
-  });
-}

package/agent/models/AgentModeResolver.ts

@@ -1,9 +0,0 @@
-import type { PluginOptions } from "../../types.js";
-
-export class AgentModeResolver {
-  constructor(private readonly options: PluginOptions) {}
-
-  resolve(modeName?: string | null) {
-    return this.options.modes.find((mode) => mode.name === modeName) ?? this.options.modes[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,
-      }),
-    });
-  }
-}