feat: enhance API tool handling and context management in middleware

Author: NoOne7135

agent/middleware/apiBasedTools.ts

@@ -1,7 +1,10 @@
 import { ToolMessage } from "@langchain/core/messages";
 import { createMiddleware } from "langchain";
-import { logger } from "adminforth";
-import { type ApiBasedTool } from "../../apiBasedTools.js";
+import { logger, type AdminUser, type IAdminForth } from "adminforth";
+import {
+  formatApiBasedToolCall,
+  type ApiBasedTool,
+} from "../../apiBasedTools.js";
 import {
   createToolCallTracker,
   type ToolCallEventSink,
@@ -46,6 +49,7 @@ function getEnabledApiToolNames(messages: unknown[]) {
 
 export function createApiBasedToolsMiddleware(
   apiBasedTools: Record<string, ApiBasedTool>,
+  adminforth: IAdminForth,
 ) {
   const alwaysAvailableApiToolNames = new Set<string>(ALWAYS_AVAILABLE_API_TOOL_NAMES);
   const dynamicTools = Object.fromEntries(
@@ -71,14 +75,33 @@ export function createApiBasedToolsMiddleware(
     async wrapToolCall(request, handler) {
       const startedAt = Date.now();
       const toolInput = JSON.stringify(request.toolCall.args ?? {});
-      const { emitToolCallEvent } = request.runtime.context as {
+      const { adminUser, emitToolCallEvent, userTimeZone } = request.runtime.context as {
+        adminUser: AdminUser;
         emitToolCallEvent: ToolCallEventSink;
+        userTimeZone: string;
       };
+      const toolArgs = (request.toolCall.args ?? {}) as Record<string, unknown>;
+      let toolInfo: string | undefined;
+
+      if (request.toolCall.name === "fetch_skill") {
+        toolInfo = `Load ${(toolArgs.skillName as string).split("_").join(" ")} skill`;
+      } else if (request.toolCall.name === "fetch_tool_schema") {
+        toolInfo = `Load ${(toolArgs.toolName as string).split("_").join(" ")} tool `;
+      } else {
+        toolInfo = await formatApiBasedToolCall({
+          adminforth,
+          adminUser,
+          inputs: toolArgs,
+          toolName: request.toolCall.name,
+          userTimeZone,
+        });
+      }
       const toolCallTracker = createToolCallTracker({
         emit: emitToolCallEvent,
         toolCallId: request.toolCall.id,
         toolName: request.toolCall.name,
-        input: (request.toolCall.args ?? {}) as Record<string, unknown>,
+        toolInfo,
+        input: toolArgs,
         startedAt,
       });
       toolCallTracker.start();

agent/simpleAgent.ts

@@ -1,5 +1,10 @@
 import { createAgent, summarizationMiddleware } from "langchain";
-import { logger, type AdminUser, type CompletionAdapter } from "adminforth";
+import {
+  logger,
+  type AdminUser,
+  type CompletionAdapter,
+  type IAdminForth,
+} from "adminforth";
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
 import {type BaseCheckpointSaver, type Messages } from "@langchain/langgraph";
 import type { LLMResult } from "@langchain/core/outputs";
@@ -219,6 +224,7 @@ export async function callAgent(params: {
   checkpointer?: BaseCheckpointSaver;
   messages: Messages;
   adminUser: AdminUser;
+  adminforth: IAdminForth;
   apiBasedTools: Record<string, ApiBasedTool>;
   customComponentsDir: string;
   sessionId: string;
@@ -234,6 +240,7 @@ export async function callAgent(params: {
     checkpointer,
     messages,
     adminUser,
+    adminforth,
     apiBasedTools,
     customComponentsDir,
     sessionId,
@@ -244,7 +251,7 @@ export async function callAgent(params: {
   } = params;
 
   const tools = await createAgentTools(customComponentsDir, apiBasedTools);
-  const apiBasedToolsMiddleware = createApiBasedToolsMiddleware(apiBasedTools);
+  const apiBasedToolsMiddleware = createApiBasedToolsMiddleware(apiBasedTools, adminforth);
   const openAiResponsesContinuationMiddleware =
     createOpenAiResponsesContinuationMiddleware();
   const sequenceDebugMiddleware = createSequenceDebugMiddleware(

agent/toolCallEvents.ts

@@ -6,6 +6,7 @@ export type ToolCallEvent =
   | {
       toolCallId: string;
       toolName: string;
+      toolInfo?: string;
       phase: "start";
       input: string;
     }
@@ -64,6 +65,7 @@ export function createToolCallTracker(params: {
   emit: ToolCallEventSink;
   toolCallId?: string;
   toolName: string;
+  toolInfo?: string;
   input?: Record<string, unknown>;
   startedAt?: number;
 }) {
@@ -75,6 +77,7 @@ export function createToolCallTracker(params: {
       params.emit({
         toolCallId,
         toolName: params.toolName,
+        toolInfo: params.toolInfo,
         phase: "start",
         input: YAML.stringify(params.input ?? {}),
       });

apiBasedTools.ts

@@ -65,10 +65,11 @@ type ToolHttpResponse = IAdminForthHttpResponse & {
 type ToolOverrideCallParams = Pick<ApiBasedToolCallParams, 'httpExtra' | 'inputs' | 'userTimeZone'>;
 
 type ToolOverrideContext = {
-  output: unknown;
+  output?: unknown;
   adminUser?: AdminUser;
   httpExtra?: Partial<HttpExtra>;
   inputs?: Record<string, unknown>;
+  resourceLabel?: string;
   userTimeZone?: string;
   invokeTool: (toolName: string, params?: ToolOverrideCallParams) => Promise<unknown>;
 };
@@ -98,6 +99,42 @@ type DateTimeColumnType = AdminForthDataTypes.DATETIME | AdminForthDataTypes.TIM
 
 const DEFAULT_USER_TIME_ZONE = 'UTC';
 
+function getInputString(inputs: Record<string, unknown> | undefined, key: string) {
+  const value = inputs?.[key];
+
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+function getInputArrayLength(inputs: Record<string, unknown> | undefined, key: string) {
+  const value = inputs?.[key];
+
+  return Array.isArray(value) ? value.length : undefined;
+}
+
+function resourceLabel(adminforth: IAdminForth, inputs: Record<string, unknown> | undefined) {
+  const resourceId = getInputString(inputs, 'resourceId');
+  const resource = adminforth.config.resources.find((res) => res.resourceId === resourceId);
+
+  return resource?.label ?? resourceId ?? 'resource';
+}
+
+function getDataPrefix(inputs: Record<string, unknown> | undefined) {
+  const offset = typeof inputs?.offset === 'number' ? inputs.offset : undefined;
+  const limit = typeof inputs?.limit === 'number' ? inputs.limit : undefined;
+
+  if (offset !== undefined && limit !== undefined) {
+    return `${offset}-${offset + limit} `;
+  }
+
+  return limit === undefined ? '' : `${limit} `;
+}
+
+function actionText(inputs: Record<string, unknown> | undefined) {
+  const actionId = getInputString(inputs, 'actionId');
+
+  return actionId ? ` action ${actionId}` : ' action';
+}
+
 const TOOL_OVERRIDES: Record<string, ToolOverride> = {
   get_resource: {
     wipe_frontend_specific_data: [
@@ -106,11 +143,12 @@ const TOOL_OVERRIDES: Record<string, ToolOverride> = {
       'resource.options.actions[].customComponent',
       'resource.options.pageInjections',
     ],
-    format_tool: async ({ }) => {
-      return "get resource Apartments"
-    }
+    format_tool: ({ resourceLabel }) => `Get ${resourceLabel} resource`,
   },
   get_resource_data: {
+    format_tool: ({ inputs, resourceLabel }) => (
+      `Get ${getDataPrefix(inputs)}${resourceLabel}`
+    ),
     post_process_response: async ({ output, inputs, invokeTool, userTimeZone }) => {
       if (hasToolError(output)) {
         return output;
@@ -132,9 +170,37 @@ const TOOL_OVERRIDES: Record<string, ToolOverride> = {
 
       return response;
     },
-    format_tool: async ({ }) => {
-      return "get 1-20 Apartment filtered listed=yes"
-    }
+  },
+  aggregate: {
+    format_tool: ({ resourceLabel }) => `Aggregate ${resourceLabel}`,
+  },
+  start_custom_action: {
+    format_tool: ({ inputs, resourceLabel }) => `Run ${resourceLabel}${actionText(inputs)}`,
+  },
+  start_custom_bulk_action: {
+    format_tool: ({ inputs, resourceLabel }) => {
+      const recordCount = getInputArrayLength(inputs, 'recordIds');
+      const recordsText = recordCount === undefined ? '' : ` for ${recordCount} records`;
+
+      return `Run ${resourceLabel}${actionText(inputs)}${recordsText}`;
+    },
+  },
+  start_bulk_action: {
+    format_tool: ({ inputs, resourceLabel }) => {
+      const recordCount = getInputArrayLength(inputs, 'recordIds');
+      const recordsText = recordCount === undefined ? '' : ` for ${recordCount} records`;
+
+      return `Run ${resourceLabel}${actionText(inputs)}${recordsText}`;
+    },
+  },
+  create_record: {
+    format_tool: ({ resourceLabel }) => `Create ${resourceLabel}`,
+  },
+  update_record: {
+    format_tool: ({ resourceLabel }) => `Update ${resourceLabel}`,
+  },
+  delete_record: {
+    format_tool: ({ resourceLabel }) => `Delete ${resourceLabel}`,
   },
 };
 
@@ -401,6 +467,28 @@ function endpointPathToToolName(path: string) {
     .replace(/^_+|_+$/g, '');
 }
 
+export async function formatApiBasedToolCall(params: {
+  adminforth: IAdminForth;
+  adminUser?: AdminUser;
+  httpExtra?: Partial<HttpExtra>;
+  inputs?: Record<string, unknown>;
+  toolName: string;
+  userTimeZone?: string;
+}) {
+  const formatTool = TOOL_OVERRIDES[params.toolName]?.format_tool;
+
+  return await formatTool?.({
+    adminUser: params.adminUser,
+    httpExtra: params.httpExtra,
+    inputs: params.inputs,
+    resourceLabel: resourceLabel(params.adminforth, params.inputs),
+    userTimeZone: params.userTimeZone,
+    invokeTool: async () => {
+      throw new Error('Tool info formatting cannot invoke tools');
+    },
+  });
+}
+
 function normalizeCookies(cookies?: Partial<HttpExtra>['cookies']): CookieItem[] {
   if (!cookies) {
     return [];

index.ts

@@ -338,6 +338,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
               new HumanMessage(prompt),
             ],
             adminUser,
+            adminforth: this.adminforth,
             apiBasedTools: this.apiBasedTools,
             customComponentsDir: this.adminforth.config.customization.customComponentsDir,
             sessionId,