@aiscene/shared 8.0.1 → 8.0.3

package/src/mcp/tool-generator.ts

@@ -1,4 +1,4 @@
-import { parseBase64 } from '../img';
+import { parseBase64 } from '@aiscene/shared/img';
 import { z } from 'zod';
 import {
   getZodDescription,
@@ -6,20 +6,16 @@ import {
   isMidsceneLocatorField,
   unwrapZodField,
 } from '../zod-schema-utils';
+import { getErrorMessage } from './error-formatter';
 import type {
   ActionSpaceItem,
   BaseAgent,
+  ToolCliMetadata,
   ToolDefinition,
   ToolResult,
+  ToolSchema,
 } from './types';
 
-/**
- * Extract error message from unknown error type
- */
-function getErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 /**
  * Generate MCP tool description from ActionSpaceItem
  * Format: "actionName action, description. Parameters: param1 (type) - desc; param2 (type) - desc"
@@ -157,10 +153,19 @@ function transformSchemaField(
 }
 
 /**
- * Extract and transform schema from action's paramSchema
+ * Extract and transform schema from action's paramSchema.
+ *
+ * CLI and MCP both expose parameters as named fields, so the only schema
+ * shapes we can surface are ZodObject (any number of fields) or undefined
+ * (the action takes no parameters). A primitive schema like `z.string()`
+ * silently degraded to leaking the ZodString instance's prototype methods
+ * as CLI flags — see https://github.com/web-infra-dev/midscene/issues/2313.
+ * Reject such schemas up front so the next author gets a loud error
+ * instead of a silent misconfiguration at runtime.
  */
 function extractActionSchema(
   paramSchema: z.ZodTypeAny | undefined,
+  actionName: string,
 ): Record<string, z.ZodTypeAny> {
   if (!paramSchema) {
     return {};
@@ -168,7 +173,12 @@ function extractActionSchema(
 
   const shape = getZodObjectShape(paramSchema);
   if (!shape) {
-    return paramSchema as unknown as Record<string, z.ZodTypeAny>;
+    const typeName =
+      (paramSchema as unknown as { _def?: { typeName?: string } })?._def
+        ?.typeName ?? 'unknown';
+    throw new Error(
+      `Action "${actionName}" declared a non-object paramSchema (${typeName}). CLI and MCP tool schemas must be a ZodObject (e.g. z.object({ uri: z.string() })) or undefined. Wrap primitive fields in an object schema.`,
+    );
   }
 
   return Object.fromEntries(
@@ -453,25 +463,49 @@ async function captureFailureResult(
   }
 }
 
+function mergeToolCliMetadata(
+  base?: ToolCliMetadata,
+  extra?: ToolCliMetadata,
+): ToolCliMetadata | undefined {
+  const options = {
+    ...(base?.options ?? {}),
+    ...(extra?.options ?? {}),
+  };
+
+  return Object.keys(options).length > 0 ? { options } : undefined;
+}
+
 /**
  * Converts DeviceAction from actionSpace into MCP ToolDefinition
  * This is the core logic that removes need for hardcoded tool definitions
  */
 export function generateToolsFromActionSpace(
   actionSpace: ActionSpaceItem[],
-  getAgent: () => Promise<BaseAgent>,
+  getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>,
+  sanitizeArgs: (args: Record<string, unknown>) => Record<string, unknown> = (
+    args,
+  ) => args,
+  initArgSchema: ToolSchema = {},
+  initArgCliMetadata?: ToolCliMetadata,
 ): ToolDefinition[] {
   return actionSpace.map((action) => {
-    const schema = extractActionSchema(action.paramSchema as z.ZodTypeAny);
+    const schema = {
+      ...extractActionSchema(action.paramSchema as z.ZodTypeAny, action.name),
+      ...initArgSchema,
+    };
 
     return {
       name: action.name,
       description: describeActionForMCP(action),
       schema,
+      cli: initArgCliMetadata,
       handler: async (args: Record<string, unknown>) => {
         try {
-          const agent = await getAgent();
-          const normalizedArgs = normalizeActionArgs(args, action.paramSchema);
+          const agent = await getAgent(args);
+          const normalizedArgs = normalizeActionArgs(
+            sanitizeArgs(args),
+            action.paramSchema,
+          );
           let actionResult: unknown;
 
           try {
@@ -513,16 +547,23 @@ export function generateToolsFromActionSpace(
  * Generate common tools (screenshot, act)
  */
 export function generateCommonTools(
-  getAgent: () => Promise<BaseAgent>,
+  getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>,
+  initArgSchema: ToolSchema = {},
+  initArgCliMetadata?: ToolCliMetadata,
 ): ToolDefinition[] {
   return [
     {
       name: 'take_screenshot',
       description: 'Capture screenshot of current page/screen',
-      schema: {},
-      handler: async (): Promise<ToolResult> => {
+      schema: {
+        ...initArgSchema,
+      },
+      cli: initArgCliMetadata,
+      handler: async (
+        args: Record<string, unknown> = {},
+      ): Promise<ToolResult> => {
         try {
-          const agent = await getAgent();
+          const agent = await getAgent(args);
           const screenshot = await agent.page?.screenshotBase64();
           if (!screenshot) {
             return createErrorResult('Screenshot not available');
@@ -550,11 +591,15 @@ export function generateCommonTools(
           .describe(
             'Natural language description of the action to perform, e.g. "press Command+Space, type Safari, press Enter"',
           ),
+        ...initArgSchema,
       },
-      handler: async (args: Record<string, unknown>): Promise<ToolResult> => {
+      cli: mergeToolCliMetadata(undefined, initArgCliMetadata),
+      handler: async (
+        args: Record<string, unknown> = {},
+      ): Promise<ToolResult> => {
         const prompt = args.prompt as string;
         try {
-          const agent = await getAgent();
+          const agent = await getAgent(args);
           if (!agent.aiAction) {
             return createErrorResult('act is not supported by this agent');
           }
@@ -576,5 +621,38 @@ export function generateCommonTools(
         }
       },
     },
+    {
+      name: 'assert',
+      description:
+        'Assert a natural language statement against the current page/screen.',
+      schema: {
+        prompt: z
+          .string()
+          .describe(
+            'Natural language assertion to verify, e.g. "there is a login button visible"',
+          ),
+        ...initArgSchema,
+      },
+      cli: mergeToolCliMetadata(undefined, initArgCliMetadata),
+      handler: async (
+        args: Record<string, unknown> = {},
+      ): Promise<ToolResult> => {
+        const prompt = args.prompt as string;
+        try {
+          const agent = await getAgent(args);
+          if (!agent.aiAssert) {
+            return createErrorResult('assert is not supported by this agent');
+          }
+          await agent.aiAssert(prompt);
+          return {
+            content: [{ type: 'text', text: 'Assertion passed.' }],
+          };
+        } catch (error: unknown) {
+          const errorMessage = getErrorMessage(error);
+          console.error('Error executing assert:', errorMessage);
+          return createErrorResult(`Failed to execute assert: ${errorMessage}`);
+        }
+      },
+    },
   ];
 }

package/src/mcp/types.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { z } from 'zod';
 
-// Avoid circular dependency: don't import from @midscene/core
+// Avoid circular dependency: don't import from @aiscene/core
 // Instead, use generic types that will be provided by implementation
 
 /**
@@ -47,6 +47,15 @@ export type ToolHandler<T = Record<string, unknown>> = (
  */
 export type ToolSchema = Record<string, z.ZodTypeAny>;
 
+export interface ToolCliOption {
+  preferredName?: string;
+  aliases?: string[];
+}
+
+export interface ToolCliMetadata {
+  options?: Record<string, ToolCliOption>;
+}
+
 /**
  * Tool definition for MCP server
  */
@@ -55,6 +64,7 @@ export interface ToolDefinition<T = Record<string, unknown>> {
   description: string;
   schema: ToolSchema;
   handler: ToolHandler<T>;
+  cli?: ToolCliMetadata;
 }
 
 /**
@@ -96,6 +106,11 @@ export interface BaseAgent {
     assertion: string,
     options: Record<string, unknown>,
   ) => Promise<unknown>;
+  aiAssert?: (
+    assertion: string,
+    msg?: string,
+    options?: Record<string, unknown>,
+  ) => Promise<unknown>;
 }
 
 /**