@aiscene/shared 8.0.2 → 8.0.4

package/src/mcp/cli-report-session.ts

@@ -0,0 +1,130 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getMidsceneRunBaseDir, getMidsceneRunSubDir } from '../common';
+
+export interface CliReportSession {
+  version: 1;
+  sessionName: string;
+  targetIdentity?: string;
+  reportFileName: string;
+  reportPath: string;
+  createdAt: number;
+}
+
+const sessionDirName = 'cli-report-session';
+
+function sanitizeSessionName(sessionName: string): string {
+  return sessionName.replace(/[^a-zA-Z0-9._-]/g, '_') || 'default';
+}
+
+function sanitizeFileSegment(segment: string): string {
+  const sanitized = segment.replace(/[^a-zA-Z0-9._-]/g, '_') || 'unknown';
+  return sanitized.slice(0, 80);
+}
+
+function ensureHtmlFileName(reportFileName: string): string {
+  return reportFileName.endsWith('.html')
+    ? reportFileName
+    : `${reportFileName}.html`;
+}
+
+function formatDateForFileName(date: Date): string {
+  const pad = (value: number) => String(value).padStart(2, '0');
+  const day = [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+  ].join('-');
+  const time = [
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds()),
+  ].join('-');
+  return `${day}_${time}`;
+}
+
+function randomId(): string {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+function getCliReportSessionDir(): string {
+  const dir = join(getMidsceneRunBaseDir(), sessionDirName);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function getCliReportSessionPath(sessionName: string): string {
+  return join(
+    getCliReportSessionDir(),
+    `${sanitizeSessionName(sessionName)}.json`,
+  );
+}
+
+export function generateCliReportSession(
+  sessionName: string,
+  targetIdentity?: string,
+): CliReportSession {
+  const identitySegment = targetIdentity
+    ? `-${sanitizeFileSegment(targetIdentity)}`
+    : '';
+  const reportFileName = `${sanitizeSessionName(sessionName)}${identitySegment}-${formatDateForFileName(new Date())}-${randomId()}`;
+  const reportPath = join(
+    getMidsceneRunSubDir('report'),
+    ensureHtmlFileName(reportFileName),
+  );
+  const session: CliReportSession = {
+    version: 1,
+    sessionName,
+    ...(targetIdentity ? { targetIdentity } : {}),
+    reportFileName,
+    reportPath,
+    createdAt: Date.now(),
+  };
+  return session;
+}
+
+export function writeCliReportSession(session: CliReportSession): void {
+  writeFileSync(
+    getCliReportSessionPath(session.sessionName),
+    JSON.stringify(session, null, 2),
+    'utf-8',
+  );
+}
+
+export function createCliReportSession(
+  sessionName: string,
+  targetIdentity?: string,
+): CliReportSession {
+  const session = generateCliReportSession(sessionName, targetIdentity);
+  writeCliReportSession(session);
+  return session;
+}
+
+export function readCliReportSession(
+  sessionName: string,
+): CliReportSession | undefined {
+  const sessionPath = getCliReportSessionPath(sessionName);
+  if (!existsSync(sessionPath)) {
+    return undefined;
+  }
+
+  try {
+    const raw = readFileSync(sessionPath, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<CliReportSession>;
+    if (
+      parsed.version !== 1 ||
+      parsed.sessionName !== sessionName ||
+      typeof parsed.reportFileName !== 'string' ||
+      !parsed.reportFileName.trim() ||
+      /[\\/]/.test(parsed.reportFileName)
+    ) {
+      return undefined;
+    }
+
+    return parsed as CliReportSession;
+  } catch {
+    return undefined;
+  }
+}

package/src/mcp/error-formatter.ts

@@ -0,0 +1,52 @@
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ *
+ * Many SDK/transport layers reject with structured objects (e.g.
+ * `{ code, message }`, `{ error: { message } }`, `{ cause: { message } }`)
+ * rather than `Error` instances. `String(obj)` collapses those to
+ * `"[object Object]"`, which is useless for diagnostics. This helper walks
+ * the common shapes, falls back to `JSON.stringify`, and finally to
+ * `Object.prototype.toString.call` so that callers always get something
+ * actionable in logs and surfaced tool results.
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (error === null || error === undefined) return String(error);
+  if (typeof error !== 'object') return String(error);
+
+  const candidate = extractStringMessage(error);
+  if (candidate) return candidate;
+
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return Object.prototype.toString.call(error);
+  }
+}
+
+function extractStringMessage(error: object): string | undefined {
+  const anyError = error as {
+    message?: unknown;
+    error?: { message?: unknown };
+    cause?: { message?: unknown };
+  };
+
+  if (typeof anyError.message === 'string' && anyError.message) {
+    return anyError.message;
+  }
+  if (
+    anyError.error &&
+    typeof anyError.error.message === 'string' &&
+    anyError.error.message
+  ) {
+    return anyError.error.message;
+  }
+  if (
+    anyError.cause &&
+    typeof anyError.cause.message === 'string' &&
+    anyError.cause.message
+  ) {
+    return anyError.cause.message;
+  }
+  return undefined;
+}

package/src/mcp/index.ts

@@ -1,5 +1,7 @@
 export * from './base-server';
 export * from './base-tools';
+export * from './init-arg-utils';
+export * from './error-formatter';
 export * from './tool-generator';
 export * from './types';
 export * from './inject-report-html-plugin';

package/src/mcp/init-arg-utils.ts

@@ -0,0 +1,105 @@
+import type { z } from 'zod';
+import { getKeyAliases, isRecord } from '../key-alias-utils';
+import type { ToolSchema } from './types';
+
+function readAliasedValue(
+  args: Record<string, unknown>,
+  key: string,
+): unknown | undefined {
+  for (const alias of getKeyAliases(key)) {
+    if (alias in args) {
+      return args[alias];
+    }
+  }
+
+  return undefined;
+}
+
+function readNamespacedArg(
+  args: Record<string, unknown>,
+  namespace: string,
+  key: string,
+): unknown | undefined {
+  // Lookup order: namespace object first, then flat dotted form, then bare key
+  // fallback. Namespace-aware inputs win so multi-platform callers cannot be
+  // cross-contaminated by a top-level bare `deviceId` leaking into the wrong
+  // platform.
+  const namespacedArgs = readAliasedValue(args, namespace);
+  if (isRecord(namespacedArgs)) {
+    const nestedValue = readAliasedValue(namespacedArgs, key);
+    if (nestedValue !== undefined) {
+      return nestedValue;
+    }
+  }
+
+  const dottedValue = readAliasedValue(args, `${namespace}.${key}`);
+  if (dottedValue !== undefined) {
+    return dottedValue;
+  }
+
+  const directValue = readAliasedValue(args, key);
+  if (directValue !== undefined) {
+    return directValue;
+  }
+
+  return undefined;
+}
+
+export function extractNamespacedArgs<
+  TFieldName extends string,
+  TArgs extends Record<string, unknown> = Record<string, unknown>,
+>(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly TFieldName[],
+): TArgs | undefined {
+  const extracted: Record<string, unknown> = {};
+
+  for (const key of keys) {
+    const value = readNamespacedArg(args, namespace, key);
+    if (value !== undefined) {
+      extracted[key] = value;
+    }
+  }
+
+  return Object.keys(extracted).length > 0 ? (extracted as TArgs) : undefined;
+}
+
+export function sanitizeNamespacedArgs(
+  args: Record<string, unknown>,
+  namespace: string,
+  keys: readonly string[],
+): Record<string, unknown> {
+  const excludedKeys = new Set<string>(getKeyAliases(namespace));
+
+  for (const key of keys) {
+    for (const alias of getKeyAliases(key)) {
+      excludedKeys.add(alias);
+    }
+
+    for (const alias of getKeyAliases(`${namespace}.${key}`)) {
+      excludedKeys.add(alias);
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(args).filter(([key]) => !excludedKeys.has(key)),
+  );
+}
+
+/**
+ * Build a flat MCP tool schema whose keys are dotted `"<namespace>.<field>"`.
+ *
+ * We intentionally stay flat (rather than `{ namespace: z.object({...}) }`) so
+ * that CLI (`--android.device-id`), MCP clients, and `--help` output all share
+ * the same spelling. `readNamespacedArg` understands all three input shapes:
+ * nested namespace object, dotted flat key, and bare key fallback.
+ */
+export function createNamespacedInitArgSchema(
+  namespace: string,
+  shape: Record<string, z.ZodTypeAny>,
+): ToolSchema {
+  return Object.fromEntries(
+    Object.entries(shape).map(([key, value]) => [`${namespace}.${key}`, value]),
+  );
+}

package/src/mcp/inject-report-html-plugin.ts

@@ -10,12 +10,12 @@ interface RslibPluginApi {
 }
 
 /**
- * Rslib plugin to inject report HTML from @midscene/core dist into MCP bundle.
+ * Rslib plugin to inject report HTML from @aiscene/core dist into MCP bundle.
  * This runs after build and reads the already-injected HTML from core.
  *
  * Prerequisites:
  * - @midscene/report must be in devDependencies to ensure correct build order
- * - @midscene/core dist must exist with injected HTML
+ * - @aiscene/core dist must exist with injected HTML
  *
  * @param packageDir - The directory of the MCP package (use __dirname)
  */
@@ -35,7 +35,7 @@ export function injectReportHtmlFromCore(packageDir: string) {
 
         if (!fs.existsSync(coreUtilsPath)) {
           console.warn(
-            '[inject-report-html] @midscene/core dist not found, skipping',
+            '[inject-report-html] @aiscene/core dist not found, skipping',
           );
           return;
         }

package/src/mcp/launcher-helper.ts

@@ -11,7 +11,7 @@ export interface LaunchMCPServerOptions extends HttpLaunchOptions {
 }
 
 /**
- * Generic agent type (avoid importing from @midscene/core to prevent circular deps)
+ * Generic agent type (avoid importing from @aiscene/core to prevent circular deps)
  */
 export interface GenericAgent<TDevice = any> {
   interface: TDevice;
@@ -64,8 +64,8 @@ export interface MCPServerLauncherConfig<
  *
  * @example
  * ```typescript
- * import { createMCPServerLauncher } from '@midscene/shared/mcp';
- * import { Agent } from '@midscene/core/agent';
+ * import { createMCPServerLauncher } from '@aiscene/shared/mcp';
+ * import { Agent } from '@aiscene/core/agent';
  * import { WebMidsceneTools } from './web-tools';
  * import { WebMCPServer } from './server';
  *

package/src/mcp/tool-generator.ts

@@ -1,25 +1,21 @@
+import { parseBase64 } from '@aiscene/shared/img';
 import { z } from 'zod';
-import { parseBase64 } from '../img';
 import {
   getZodDescription,
   getZodTypeName,
   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,13 @@ export interface BaseAgent {
     assertion: string,
     options: Record<string, unknown>,
   ) => Promise<unknown>;
+  aiAssert?: (
+    assertion: string,
+    msg?: string,
+    options?: Record<string, unknown>,
+  ) => Promise<unknown>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  aiQuery?: (demand: any, opt?: any) => Promise<any>;
 }
 
 /**