feat: implement navigation functionality and enhance agent event handling

Author: NoOne7135

agent/middleware/sequenceDebug.ts

@@ -26,6 +26,9 @@ export type SequenceDebug = {
   reasoningTokens: number;
   text: string;
   textTokens: number;
+  uncachedInputTokens: number;
+  cachedInputTokens: number;
+  outputTokens: number;
   cachedTokens: number;
   responseId: string | null;
   toolCalls: SequenceDebugToolCall[];
@@ -45,13 +48,17 @@ type SequenceDebugModelCall = {
   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;
   };
@@ -82,6 +89,9 @@ function createPendingSequenceDebug(sequenceId: number): PendingSequenceDebug {
     reasoningTokens: 0,
     text: "",
     textTokens: 0,
+    uncachedInputTokens: 0,
+    cachedInputTokens: 0,
+    outputTokens: 0,
     cachedTokens: 0,
     responseId: null,
     toolCalls: [],
@@ -112,6 +122,9 @@ function finalizeSequenceDebug(sequence: PendingSequenceDebug): SequenceDebug {
     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),
@@ -133,6 +146,21 @@ 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 };
@@ -160,7 +188,7 @@ function stringifyPromptForDebug(params: {
     },
     systemMessage,
     messages,
-    ...(tools.length > 0 ? { tools } : {}),
+    ...(tools.length > 0 ? { tools: formatToolsForDebug(tools) } : {}),
     ...(toolChoice !== undefined ? { toolChoice } : {}),
     ...(modelSettings ? { modelSettings } : {}),
     ...(invocationParams ? { invocationParams } : {}),
@@ -219,6 +247,9 @@ async function countTokens(model: unknown, content: string) {
 }
 
 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")
@@ -230,16 +261,15 @@ function extractSequenceResponseDebug(message: AIMessage): SequenceDebugModelCal
     .join("");
 
   return {
-    promptTokens:
-      (message.usage_metadata as OpenAiUsageMetadata | undefined)?.input_tokens ??
-      0,
+    promptTokens,
     reasoning,
     reasoningTokens: 0,
     text: textFromBlocks || (typeof message.content === "string" ? message.content : ""),
     textTokens: 0,
-    cachedTokens:
-      (message.usage_metadata as OpenAiUsageMetadata | undefined)
-        ?.input_token_details?.cache_read ?? 0,
+    uncachedInputTokens: Math.max(promptTokens - cachedInputTokens, 0),
+    cachedInputTokens,
+    outputTokens: usageMetadata?.output_tokens ?? 0,
+    cachedTokens: cachedInputTokens,
     responseId:
       (message.response_metadata as OpenAiResponseMetadata | undefined)?.id ??
       null,
@@ -290,6 +320,9 @@ export function createSequenceDebugCollector(): SequenceDebugCollector {
       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;
@@ -387,6 +420,8 @@ export function createSequenceDebugMiddleware(
         promptTokens,
         reasoningTokens,
         textTokens,
+        uncachedInputTokens: debug.promptTokens ? debug.uncachedInputTokens : promptTokens,
+        outputTokens: debug.outputTokens || reasoningTokens + textTokens,
       });
       return response;
     },

agent/simpleAgent.ts

@@ -19,6 +19,7 @@ import {
 import type { ApiBasedTool } from "../apiBasedTools.js";
 import type { ToolCallEventSink } from "./toolCallEvents.js";
 import type { CurrentPageContext } from "./tools/getUserLocation.js";
+import type { AgentEventEmitter } from "../agentEvents.js";
 
 export const contextSchema = z.object({
   adminUser: z.custom<AdminUser>(),
@@ -27,7 +28,11 @@ export const contextSchema = z.object({
   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(),
   emitToolCallEvent: z.custom<ToolCallEventSink>(),
+  emitAgentEvent: z.custom<AgentEventEmitter>().optional(),
 });
 
 export type AgentChatModel = BaseChatModel<any, any>;
@@ -234,9 +239,12 @@ export async function callAgent(params: {
   sessionId: string;
   turnId: string;
   currentPage?: CurrentPageContext;
+  chatSurface?: string;
+  adminPublicOrigin?: string;
   userTimeZone: string;
   abortSignal?: AbortSignal;
   emitToolCallEvent: ToolCallEventSink;
+  emitAgentEvent?: AgentEventEmitter;
   sequenceDebugSink: SequenceDebugModelCallSink;
 }) {
   const {
@@ -254,9 +262,12 @@ export async function callAgent(params: {
     sessionId,
     turnId,
     currentPage,
+    chatSurface,
+    adminPublicOrigin,
     userTimeZone,
     abortSignal,
     emitToolCallEvent,
+    emitAgentEvent,
     sequenceDebugSink,
   } = params;
 
@@ -305,7 +316,11 @@ export async function callAgent(params: {
       turnId,
       abortSignal,
       currentPage,
+      chatSurface,
+      adminBaseUrl: adminforth.config.baseUrlSlashed,
+      adminPublicOrigin,
       emitToolCallEvent,
+      emitAgentEvent,
     },
   });
 }

agent/systemPrompt.ts

@@ -70,12 +70,16 @@ export function buildAgentTurnSystemPrompt(input: {
   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),
-  ].join("\n\n");
+  ].filter(Boolean).join("\n\n");
 }
 
 function formatResources(resources: AdminForthResource[]) {
@@ -124,6 +128,7 @@ export async function buildAgentSystemPrompt(
     "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.",
   ];
 

agent/tools/index.ts

@@ -4,6 +4,7 @@ import { createFetchToolSchemaTool } from "./fetchToolSchema.js";
 import type { ApiBasedTool } from "../../apiBasedTools.js";
 import { createApiTool } from "./apiTool.js";
 import { createGetUserLocationTool } from "./getUserLocation.js";
+import { createNavigateUserTool } from "./navigateUser.js";
 
 export const ALWAYS_AVAILABLE_API_TOOL_NAMES = ["get_resource"] as const;
 
@@ -23,6 +24,7 @@ export async function createAgentTools(
       return createApiTool(toolName, apiBasedTool);
     }),
     createGetUserLocationTool(),
+    createNavigateUserTool(),
     await createFetchSkillTool(customComponentsDir, pluginCustomFolderPaths),
     await createFetchToolSchemaTool(apiBasedTools),
   ];