@aiscene/shared 8.0.1 → 8.0.3

package/src/cli/cli-runner.ts

@@ -9,6 +9,12 @@ import type {
   ToolResult,
   ToolResultContent,
 } from '../mcp/types';
+import {
+  formatCliValidationError,
+  getCliOptionDisplay,
+  parseCliArgs,
+} from './cli-args';
+import { CLIError } from './cli-error';
 
 const debug = getDebug('cli-runner');
 
@@ -32,58 +38,8 @@ export interface CLIRunnerOptions {
   extraCommands?: CLIExtraCommand[];
 }
 
-export class CLIError extends Error {
-  constructor(
-    message: string,
-    public exitCode = 1,
-  ) {
-    super(message);
-  }
-}
-
-export function parseValue(raw: string): unknown {
-  // JSON objects/arrays
-  if (raw.startsWith('{') || raw.startsWith('[')) {
-    try {
-      return JSON.parse(raw);
-    } catch {
-      // Not valid JSON, treat as string below
-    }
-  }
-
-  // Numbers
-  if (/^-?\d+(\.\d+)?$/.test(raw)) {
-    return Number(raw);
-  }
-
-  return raw;
-}
-
-export function parseCliArgs(args: string[]): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (!arg.startsWith('--')) continue;
-
-    const body = arg.slice(2);
-    const eqIdx = body.indexOf('=');
-
-    if (eqIdx >= 0) {
-      // --key=value
-      result[body.slice(0, eqIdx)] = parseValue(body.slice(eqIdx + 1));
-    } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-      // --key value
-      i++;
-      result[body] = parseValue(args[i]);
-    } else {
-      // --flag (boolean)
-      result[body] = true;
-    }
-  }
-
-  return result;
-}
+export { parseCliArgs, parseValue } from './cli-args';
+export { CLIError, reportCLIError } from './cli-error';
 
 function outputContentItem(item: ToolResultContent, isError: boolean): void {
   switch (item.type) {
@@ -128,10 +84,23 @@ function printCommandHelp(scriptName: string, cmd: CLICommand): void {
 
   const schemaEntries = Object.entries(def.schema);
   if (schemaEntries.length > 0) {
+    const optionWidth = Math.max(
+      22,
+      ...schemaEntries.map(
+        ([key]) =>
+          getCliOptionDisplay(key, def.cli?.options?.[key]).label.length,
+      ),
+    );
     console.log('\nOptions:');
     for (const [key, zodType] of schemaEntries) {
+      const { label, aliases } = getCliOptionDisplay(
+        key,
+        def.cli?.options?.[key],
+      );
       const desc = zodType.description ?? '';
-      console.log(`  --${key.padEnd(20)} ${desc}`);
+      const aliasText =
+        aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : '';
+      console.log(`  ${label.padEnd(optionWidth)} ${desc}${aliasText}`);
     }
   }
 }
@@ -158,8 +127,10 @@ function printHelp(
   console.log(`\nRun "${scriptName} <command> --help" for more info.`);
 }
 
+type AnyMidsceneTools = BaseMidsceneTools<any, any>;
+
 export async function runToolsCLI(
-  tools: BaseMidsceneTools,
+  tools: AnyMidsceneTools,
   scriptName: string,
   options?: CLIRunnerOptions,
 ): Promise<void> {
@@ -227,14 +198,24 @@ export async function runToolsCLI(
   }
 
   const parsedArgs = parseCliArgs(restArgs);
-  debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
-
   if (parsedArgs.help === true) {
     debug('showing command help for: %s', match.name);
     printCommandHelp(scriptName, match);
     return;
   }
 
+  const cliValidationError = formatCliValidationError(
+    scriptName,
+    match.name,
+    match.def,
+    parsedArgs,
+  );
+  if (cliValidationError) {
+    throw new CLIError(cliValidationError);
+  }
+
+  debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
+
   const result = await match.def.handler(parsedArgs);
   debug(
     'command %s completed, isError: %s',

package/src/cli/index.ts

@@ -1,8 +1,4 @@
-export {
-  runToolsCLI,
-  CLIError,
-  parseValue,
-  parseCliArgs,
-  removePrefix,
-} from './cli-runner';
+export { CLIError, reportCLIError } from './cli-error';
+export { parseCliArgs, parseValue } from './cli-args';
+export { runToolsCLI, removePrefix } from './cli-runner';
 export type { CLIRunnerOptions, CLIExtraCommand } from './cli-runner';

package/src/constants/example-code.ts

@@ -28,8 +28,8 @@ aiQuery<T>(queryObject: Record<string, string>): Promise<T> // Extracts data fro
 // The following is test code for Midscene AI, for reference
 // The following is Playwright syntax, you can use Playwright to assist in test generation
 import { test as base } from '@playwright/test';
-import type { PlayWrightAiFixtureType } from '@midscene/web/playwright';
-import { PlaywrightAiFixture } from '@midscene/web/playwright';
+import type { PlayWrightAiFixtureType } from '@aiscene/web/playwright';
+import { PlaywrightAiFixture } from '@aiscene/web/playwright';
 
 const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({
   waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms

package/src/constants/index.ts

@@ -17,6 +17,16 @@ export enum NodeType {
 
 export const PLAYGROUND_SERVER_PORT = 5800;
 export const SCRCPY_SERVER_PORT = 5700;
+export const SCRCPY_ADB_CONNECT_TIMEOUT_MS = 10_000;
+export const SCRCPY_PUSH_TIMEOUT_MS = 10_000;
+export const SCRCPY_START_TIMEOUT_MS = 15_000;
+export const SCRCPY_VIDEO_STREAM_TIMEOUT_MS = 15_000;
+export const SCRCPY_PREVIEW_METADATA_TIMEOUT_MS =
+  SCRCPY_ADB_CONNECT_TIMEOUT_MS +
+  SCRCPY_PUSH_TIMEOUT_MS +
+  SCRCPY_START_TIMEOUT_MS +
+  SCRCPY_VIDEO_STREAM_TIMEOUT_MS +
+  5_000;
 
 // WebDriver constants
 export const WEBDRIVER_ELEMENT_ID_KEY = 'element-6066-11e4-a52e-4f735466cecf';

package/src/env/model-config-manager.ts

@@ -68,14 +68,17 @@ export class ModelConfigManager {
     this.modelConfigMap = {
       default: {
         ...defaultConfig,
+        intent: 'default',
         createOpenAIClient: this.createOpenAIClientFn,
       },
       insight: {
         ...(insightConfig || defaultConfig),
+        intent: 'insight',
         createOpenAIClient: this.createOpenAIClientFn,
       },
       planning: {
         ...(planningConfig || defaultConfig),
+        intent: 'planning',
         createOpenAIClient: this.createOpenAIClientFn,
       },
     };

package/src/env/parse-model-config.ts

@@ -24,10 +24,26 @@ import {
 } from './types';
 
 import { getDebug } from '../logger';
+
 import { assert } from '../utils';
 import { maskConfig, parseJson } from './helper';
 import { initDebugConfig } from './init-debug';
 
+declare const __VERSION__: string | undefined;
+
+const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
+
+const getCurrentVersion = (): string => {
+  if (typeof __VERSION__ !== 'undefined' && __VERSION__) {
+    return __VERSION__;
+  }
+
+  return 'unknown';
+};
+
+const getInvalidModelFamilyMessage = (modelFamily: TModelFamily): string =>
+  `Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
+
 type TModelConfigKeys =
   | typeof INSIGHT_MODEL_CONFIG_KEYS
   | typeof PLANNING_MODEL_CONFIG_KEYS
@@ -70,7 +86,7 @@ export const getUITarsModelVersion = (
  */
 export const validateModelFamily = (modelFamily?: TModelFamily): void => {
   if (modelFamily && !MODEL_FAMILY_VALUES.includes(modelFamily as any)) {
-    throw new Error(`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}`);
+    throw new Error(getInvalidModelFamilyMessage(modelFamily));
   }
 };
 
@@ -228,6 +244,7 @@ export const parseOpenaiSdkConfig = ({
     modelName: modelName!,
     modelDescription,
     intent: '-' as any,
+    slot: '-' as any,
     timeout: provider[keys.timeout]
       ? Number(provider[keys.timeout])
       : undefined,
@@ -292,6 +309,7 @@ export const decideModelConfigFromIntentConfig = (
     useLegacyLogic: intent === 'default',
   });
   finalResult.intent = intent;
+  finalResult.slot = intent;
 
   debugLog(
     'decideModelConfig result by agent.modelConfig() with intent',

package/src/env/types.ts

@@ -69,6 +69,8 @@ export const MIDSCENE_ANDROID_IME_STRATEGY = 'MIDSCENE_ANDROID_IME_STRATEGY';
 
 export const MIDSCENE_IOS_DEVICE_UDID = 'MIDSCENE_IOS_DEVICE_UDID';
 export const MIDSCENE_IOS_SIMULATOR_UDID = 'MIDSCENE_IOS_SIMULATOR_UDID';
+export const MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE =
+  'MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE';
 
 export const MIDSCENE_CACHE = 'MIDSCENE_CACHE';
 export const MIDSCENE_USE_VLM_UI_TARS = 'MIDSCENE_USE_VLM_UI_TARS';
@@ -425,7 +427,7 @@ export enum UITarsModelVersion {
 
 /**
  * Callback to create custom OpenAI client instance
- * @param config - Resolved model configuration including apiKey, baseURL, modelName, intent, etc.
+ * @param config - Resolved model configuration including apiKey, baseURL, modelName, intent, slot, etc.
  * @returns OpenAI client instance (can be wrapped with langsmith, langfuse, etc.)
  *
  * Note: Wrapper functions like langsmith's wrapOpenAI() return the same OpenAI instance
@@ -519,9 +521,16 @@ export interface IModelConfig {
   uiTarsModelVersion?: UITarsModelVersion;
   modelDescription: string;
   /**
-   * original intent from the config
+   * The semantic intent this config is requested for.
+   * For example, getModelConfig('planning') always returns intent === 'planning'.
    */
   intent: TIntent;
+  /**
+   * The model-config slot this config was resolved from.
+   * For example, getModelConfig('planning') may resolve from slot === 'default'
+   * when MIDSCENE_PLANNING_MODEL_NAME is not configured.
+   */
+  slot: TIntent;
   /**
    * Custom OpenAI client factory function
    *

package/src/env/utils.ts

@@ -13,56 +13,6 @@ export const globalConfigManager = new GlobalConfigManager();
 globalConfigManager.registerModelConfigManager(globalModelConfigManager);
 globalModelConfigManager.registerGlobalConfigManager(globalConfigManager);
 
-/**
- * Interface for devices that support getTimestamp method.
- * This is a minimal interface to avoid circular dependencies with @midscene/core.
- */
-export interface DeviceWithTimestamp {
-  getTimestamp?: () => Promise<number>;
-}
-
-/**
- * Get the current timestamp, optionally from the target device.
- *
- * When useDeviceTimestamp is enabled and a device with getTimestamp is provided,
- * this function will return the device's time. Otherwise, it returns the system time.
- *
- * This is useful when:
- * - Testing on devices with different time zones
- * - Debugging time-sensitive features
- * - The system clock and device clock are not synchronized
- *
- * @param device Optional device interface that supports getTimestamp
- * @param useDeviceTimestamp Whether to use device timestamp (from agent config)
- * @returns Timestamp in milliseconds
- *
- * @example
- * // Without device - always returns system time
- * const systemTime = await getCurrentTime();
- *
- * @example
- * // With device and config enabled - returns device time
- * const deviceTime = await getCurrentTime(androidDevice, true);
- */
-export async function getCurrentTime(
-  device?: DeviceWithTimestamp,
-  useDeviceTimestamp?: boolean,
-): Promise<number> {
-  if (useDeviceTimestamp && device?.getTimestamp) {
-    try {
-      return await device.getTimestamp();
-    } catch (error) {
-      // Fall back to system time if device time retrieval fails
-      console.warn(
-        `Failed to get device time, falling back to system time: ${error}`,
-      );
-      return Date.now();
-    }
-  }
-
-  return Date.now();
-}
-
 export const getPreferredLanguage = () => {
   const prefer = globalConfigManager.getEnvConfigValue(
     MIDSCENE_PREFERRED_LANGUAGE,

package/src/extractor/index.ts

@@ -43,6 +43,6 @@ export {
   getElementXpath,
 } from './locator';
 
-export { generateElementByRect } from './dom-util';
+export { generateElementByPoint, generateElementByRect } from './dom-util';
 
 export { isNotContainerElement } from './dom-util';

package/src/img/index.ts

@@ -3,6 +3,8 @@ export {
   isValidPNGImageBuffer,
   isValidJPEGImageBuffer,
   isValidImageBuffer,
+  validateScreenshotBuffer,
+  type ValidateScreenshotBufferOptions,
 } from './info';
 export {
   resizeAndConvertImgBuffer,

package/src/img/info.ts

@@ -73,3 +73,30 @@ export function isValidJPEGImageBuffer(buffer: Buffer): boolean {
 export function isValidImageBuffer(buffer: Buffer): boolean {
   return isValidPNGImageBuffer(buffer) || isValidJPEGImageBuffer(buffer);
 }
+
+export interface ValidateScreenshotBufferOptions {
+  label: string;
+  minBufferSize?: number;
+}
+
+export function validateScreenshotBuffer(
+  screenshotBuffer: Buffer | undefined,
+  { label, minBufferSize = 0 }: ValidateScreenshotBufferOptions,
+): asserts screenshotBuffer is Buffer {
+  const bufferSize = screenshotBuffer?.length ?? 0;
+  if (!screenshotBuffer || bufferSize === 0) {
+    throw new Error(
+      `${label} validation failed: buffer size ${bufferSize} bytes`,
+    );
+  }
+
+  if (!isValidImageBuffer(screenshotBuffer)) {
+    throw new Error(`${label} buffer has invalid image format`);
+  }
+
+  if (minBufferSize > 0 && bufferSize < minBufferSize) {
+    throw new Error(
+      `${label} validation failed: buffer size ${bufferSize} bytes (minimum: ${minBufferSize})`,
+    );
+  }
+}

package/src/key-alias-utils.ts

@@ -0,0 +1,23 @@
+/**
+ * Internal-only helpers for CLI/MCP argument key aliasing.
+ * Not re-exported from the package entry point — keep consumers within
+ * `cli/` and `mcp/`.
+ */
+
+export function kebabToCamel(str: string): string {
+  return str.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+export function camelToKebab(str: string): string {
+  return str
+    .replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+    .replace(/^-/, '');
+}
+
+export function getKeyAliases(key: string): string[] {
+  return [...new Set([key, kebabToCamel(key), camelToKebab(key)])];
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/mcp/base-server.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import type { ParseArgsConfig } from 'node:util';
-import { setIsMcp } from '../utils';
+import { setIsMcp } from '@aiscene/shared/utils';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -9,6 +9,7 @@ import express, {
   type Request,
   type Response,
 } from 'express';
+import { getErrorMessage } from './error-formatter';
 import type { IMidsceneTools } from './types';
 
 export interface BaseMCPServerConfig {
@@ -119,7 +120,7 @@ export abstract class BaseMCPServer {
     try {
       await this.toolsManager.initTools();
     } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       console.error(`Failed to initialize tools: ${message}`);
       console.error('Tools will be initialized on first use');
     }
@@ -160,7 +161,7 @@ export abstract class BaseMCPServer {
     try {
       await this.mcpServer.connect(transport);
     } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       console.error(`Failed to connect MCP stdio transport: ${message}`);
       throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
     }
@@ -282,7 +283,7 @@ export abstract class BaseMCPServer {
             .json({ error: 'Invalid session or GET without session' });
         }
       } catch (error: unknown) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         const duration = Date.now() - startTime;
         console.error(
           `[${new Date().toISOString()}] [${requestId}] MCP request error after ${duration}ms: ${message}`,
@@ -336,8 +337,7 @@ export abstract class BaseMCPServer {
           try {
             await session.transport.close();
           } catch (error: unknown) {
-            const message =
-              error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(
               `Failed to close session ${session.transport.sessionId}: ${message}`,
             );
@@ -390,7 +390,7 @@ export abstract class BaseMCPServer {
     try {
       await this.mcpServer.connect(transport);
     } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       console.error(
         `[${new Date().toISOString()}] Failed to connect MCP transport: ${message}`,
       );
@@ -425,8 +425,7 @@ export abstract class BaseMCPServer {
               `[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`,
             );
           } catch (error: unknown) {
-            const message =
-              error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(
               `[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`,
             );
@@ -455,8 +454,7 @@ export abstract class BaseMCPServer {
         try {
           session.transport.close();
         } catch (error: unknown) {
-          const message =
-            error instanceof Error ? error.message : String(error);
+          const message = getErrorMessage(error);
           console.error(`Error closing session during shutdown: ${message}`);
         }
       }
@@ -475,7 +473,7 @@ export abstract class BaseMCPServer {
           this.performCleanup().finally(() => process.exit(1));
         }, 5000);
       } catch (error: unknown) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         console.error(`Error closing HTTP server: ${message}`);
         this.performCleanup().finally(() => process.exit(1));
       }