@aiscene/shared 8.0.1 → 8.0.3

package/dist/types/cli/cli-runner.d.ts

@@ -12,11 +12,8 @@ export interface CLIRunnerOptions {
     version?: string;
     extraCommands?: CLIExtraCommand[];
 }
-export declare class CLIError extends Error {
-    exitCode: number;
-    constructor(message: string, exitCode?: number);
-}
-export declare function parseValue(raw: string): unknown;
-export declare function parseCliArgs(args: string[]): Record<string, unknown>;
+export { parseCliArgs, parseValue } from './cli-args';
+export { CLIError, reportCLIError } from './cli-error';
 export declare function removePrefix(name: string, prefix?: string): string;
-export declare function runToolsCLI(tools: BaseMidsceneTools, scriptName: string, options?: CLIRunnerOptions): Promise<void>;
+type AnyMidsceneTools = BaseMidsceneTools<any, any>;
+export declare function runToolsCLI(tools: AnyMidsceneTools, scriptName: string, options?: CLIRunnerOptions): Promise<void>;

package/dist/types/cli/index.d.ts

@@ -1,2 +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/dist/types/constants/example-code.d.ts

@@ -1,2 +1,2 @@
-export declare const PLAYWRIGHT_EXAMPLE_CODE = "\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nIMPORTANT: Follow these exact type signatures for AI functions:\n\n// Type signatures for AI functions:\naiAct(prompt: string, options?: { cacheable?: boolean, deepThink?: 'unset' | true | false }): Promise<void>\naiInput(text: string, locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiTap(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiHover(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiDoubleClick(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiKeyboardPress(key: string, locate?: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiScroll(locate: string | undefined, options: {\n  direction?: 'up' | 'down' | 'left' | 'right',\n  scrollType?: 'singleAction' | 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft',\n  distance?: number | null,\n  deepLocate?: boolean,\n  xpath?: string,\n  cacheable?: boolean\n}): Promise<void>\naiAssert(assertion: string, options?: { errorMessage?: string }): Promise<void>\naiWaitFor(prompt: string, options?: { timeout?: number }): Promise<void>\naiQuery<T>(queryObject: Record<string, string>): Promise<T> // Extracts data from page based on descriptions\n\n// examples:\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nimport { test as base } from '@playwright/test';\nimport type { PlayWrightAiFixtureType } from '@midscene/web/playwright';\nimport { PlaywrightAiFixture } from '@midscene/web/playwright';\n\nconst test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({\n  waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms\n}));\n\n\ntest.beforeEach(async ({ page }) => {\n  await page.goto('https://www.xxx.com/');\n  await page.setViewportSize({ width: 1920, height: 1080 });\n});\n\ntest('ai shop', async ({\n  aiAct,\n  aiInput,\n  aiAssert,\n  aiQuery,\n  aiKeyboardPress,\n  aiHover,\n  aiTap,\n  aiWaitFor,\n  agentForPage,\n  page,\n}) => {\n  // login\n  await aiAssert('The page shows the login interface');\n  await aiInput('user_name', 'in user name input');\n  await aiInput('password', 'in password input');\n  await aiKeyboardPress('Enter', 'Login Button');\n\n  // check the login success\n  await aiWaitFor('The page shows that the loading is complete');\n  await aiAssert('The current page shows the product detail page');\n\n  // check the product info\n  const dataA = await aiQuery({\n    userInfo: 'User information in the format {name: string}',\n    theFirstProductInfo: 'The first product info in the format {name: string, price: number}',\n  });\n  expect(dataA.theFirstProductInfo.name).toBe('xxx');\n  expect(dataA.theFirstProductInfo.price).toBe(100);\n\n\n  // add to cart\n  await aiTap('click add to cart button');\n  \n  await aiTap('click right top cart icon');\n  await aiAssert('The cart icon shows the number 1');\n});\n";
+export declare const PLAYWRIGHT_EXAMPLE_CODE = "\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nIMPORTANT: Follow these exact type signatures for AI functions:\n\n// Type signatures for AI functions:\naiAct(prompt: string, options?: { cacheable?: boolean, deepThink?: 'unset' | true | false }): Promise<void>\naiInput(text: string, locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiTap(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiHover(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiDoubleClick(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiKeyboardPress(key: string, locate?: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>\naiScroll(locate: string | undefined, options: {\n  direction?: 'up' | 'down' | 'left' | 'right',\n  scrollType?: 'singleAction' | 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft',\n  distance?: number | null,\n  deepLocate?: boolean,\n  xpath?: string,\n  cacheable?: boolean\n}): Promise<void>\naiAssert(assertion: string, options?: { errorMessage?: string }): Promise<void>\naiWaitFor(prompt: string, options?: { timeout?: number }): Promise<void>\naiQuery<T>(queryObject: Record<string, string>): Promise<T> // Extracts data from page based on descriptions\n\n// examples:\n// Reference the following code to generate Midscene test cases\n// The following is test code for Midscene AI, for reference\n// The following is Playwright syntax, you can use Playwright to assist in test generation\nimport { test as base } from '@playwright/test';\nimport type { PlayWrightAiFixtureType } from '@aiscene/web/playwright';\nimport { PlaywrightAiFixture } from '@aiscene/web/playwright';\n\nconst test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({\n  waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms\n}));\n\n\ntest.beforeEach(async ({ page }) => {\n  await page.goto('https://www.xxx.com/');\n  await page.setViewportSize({ width: 1920, height: 1080 });\n});\n\ntest('ai shop', async ({\n  aiAct,\n  aiInput,\n  aiAssert,\n  aiQuery,\n  aiKeyboardPress,\n  aiHover,\n  aiTap,\n  aiWaitFor,\n  agentForPage,\n  page,\n}) => {\n  // login\n  await aiAssert('The page shows the login interface');\n  await aiInput('user_name', 'in user name input');\n  await aiInput('password', 'in password input');\n  await aiKeyboardPress('Enter', 'Login Button');\n\n  // check the login success\n  await aiWaitFor('The page shows that the loading is complete');\n  await aiAssert('The current page shows the product detail page');\n\n  // check the product info\n  const dataA = await aiQuery({\n    userInfo: 'User information in the format {name: string}',\n    theFirstProductInfo: 'The first product info in the format {name: string, price: number}',\n  });\n  expect(dataA.theFirstProductInfo.name).toBe('xxx');\n  expect(dataA.theFirstProductInfo.price).toBe(100);\n\n\n  // add to cart\n  await aiTap('click add to cart button');\n  \n  await aiTap('click right top cart icon');\n  await aiAssert('The cart icon shows the number 1');\n});\n";
 export declare const YAML_EXAMPLE_CODE = "\nCRITICAL - YAML Indentation Rules:\nFor actions with additional parameters (aiScroll, aiInput, aiKeyboardPress), the parameters must be SIBLING keys at the SAME indentation level as the action key, NOT nested children indented further.\nCORRECT (parameters align with the action key):\n      - aiScroll:\n        direction: 'down'\n        scrollType: 'singleAction'\n        distance: 500\n        locate: \"main content area\"\n      - aiInput: 'text value'\n        locate: 'input field description'\nWRONG (parameters are indented further than the action key, DO NOT do this):\n      - aiScroll:\n          direction: 'down'\n          scrollType: 'singleAction'\n      - aiInput: 'text value'\n          locate: 'input field description'\n\n1. Format:\n\nweb:\n  url: \"starting_url\"\n  viewportWidth: 1280\n  viewportHeight: 960\n\ntasks:\n  - name: \"descriptive task name\"\n    flow:\n      - aiTap: \"element description\"\n        xpath: '/html/body/div[1]/button[1]'\n      - aiInput: 'text value'\n        locate: 'input field description'\n        xpath: '/html/body/div[1]/input[1]'\n      - aiScroll:\n        direction: 'down'\n        scrollType: 'singleAction'\n        distance: 500\n        locate: \"scrollable area description\"\n        xpath: '/html/body/div[1]/main[1]'\n      - aiAssert: \"expected state\"\n      - sleep: 1000\n\n2. Action Types:\n- aiTap: for clicks (natural language targeting)\n- aiInput: for text input with 'locate' field\n- aiScroll: with direction and scrollType\n- aiAssert: for validations\n- sleep: for delays (milliseconds)\n\n\n\nYAML type\ntasks:\n  - name: <name>\n    continueOnError: <boolean> # Optional, whether to continue to the next task on error, defaults to false.\n    flow:\n      # Auto Planning (.ai)\n      # ----------------\n\n      # Perform an interaction. `ai` is a shorthand for `aiAct`.\n      - ai: <prompt>\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # This usage is the same as `ai`.\n      - aiAct: <prompt>\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Instant Action (.aiTap, .aiDoubleClick, .aiHover, .aiInput, .aiKeyboardPress, .aiScroll)\n      # ----------------\n\n      # Tap an element described by a prompt.\n      - aiTap: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Double click an element described by a prompt.\n      - aiDoubleClick: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Hover over an element described by a prompt.\n      - aiHover: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Input text into an element described by a prompt.\n      - aiInput: <final text content of the input>\n        locate: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Press a key (e.g., Enter, Tab, Escape) on an element described by a prompt.\n      - aiKeyboardPress: <key>\n        locate: <prompt>\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Scroll globally or on an element described by a prompt.\n      - aiScroll:\n        direction: 'up' # or 'down' | 'left' | 'right'\n        scrollType: 'singleAction' # or 'scrollToTop' | 'scrollToBottom' | 'scrollToLeft' | 'scrollToRight'\n        distance: <number> # Optional, the scroll distance in pixels.\n        locate: <prompt> # Optional, the element to scroll on.\n        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.\n        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.\n        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.\n\n      # Record the current screenshot with a description in the report file.\n      - recordToReport: <title> # Optional, the title of the screenshot. If not provided, the title will be 'untitled'.\n        content: <content> # Optional, the description of the screenshot.\n\n      # Data Extraction\n      # ----------------\n\n      # Perform a query that returns a JSON object.\n      - aiQuery: <prompt> # Remember to describe the format of the result in the prompt.\n        name: <name> # The key for the query result in the JSON output.\n\n      # More APIs\n      # ----------------\n\n      # Wait for a condition to be met, with a timeout (in ms, optional, defaults to 30000).\n      - aiWaitFor: <prompt>\n        timeout: <ms>\n\n      # Perform an assertion.\n      - aiAssert: <prompt>\n        errorMessage: <error-message> # Optional, the error message to print if the assertion fails.\n\n      # Wait for a specified amount of time.\n      - sleep: <ms>\n\n      # Execute a piece of JavaScript code in the web page context.\n      - javascript: <javascript>\n        name: <name> # Optional, assign a name to the return value, which will be used as a key in the JSON output.\n\n  - name: <name>\n    flow:\n      # ...\n";

package/dist/types/constants/index.d.ts

@@ -13,6 +13,11 @@ export declare enum NodeType {
 }
 export declare const PLAYGROUND_SERVER_PORT = 5800;
 export declare const SCRCPY_SERVER_PORT = 5700;
+export declare const SCRCPY_ADB_CONNECT_TIMEOUT_MS = 10000;
+export declare const SCRCPY_PUSH_TIMEOUT_MS = 10000;
+export declare const SCRCPY_START_TIMEOUT_MS = 15000;
+export declare const SCRCPY_VIDEO_STREAM_TIMEOUT_MS = 15000;
+export declare const SCRCPY_PREVIEW_METADATA_TIMEOUT_MS: number;
 export declare const WEBDRIVER_ELEMENT_ID_KEY = "element-6066-11e4-a52e-4f735466cecf";
 export declare const DEFAULT_WDA_PORT = 8100;
 export declare const DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT = 5000;

package/dist/types/env/types.d.ts

@@ -53,6 +53,7 @@ export declare const MIDSCENE_ADB_REMOTE_PORT = "MIDSCENE_ADB_REMOTE_PORT";
 export declare const MIDSCENE_ANDROID_IME_STRATEGY = "MIDSCENE_ANDROID_IME_STRATEGY";
 export declare const MIDSCENE_IOS_DEVICE_UDID = "MIDSCENE_IOS_DEVICE_UDID";
 export declare const MIDSCENE_IOS_SIMULATOR_UDID = "MIDSCENE_IOS_SIMULATOR_UDID";
+export declare const MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE = "MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE";
 export declare const MIDSCENE_CACHE = "MIDSCENE_CACHE";
 export declare const MIDSCENE_USE_VLM_UI_TARS = "MIDSCENE_USE_VLM_UI_TARS";
 export declare const MIDSCENE_USE_QWEN_VL = "MIDSCENE_USE_QWEN_VL";
@@ -203,7 +204,7 @@ export declare 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
@@ -293,9 +294,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/dist/types/env/utils.d.ts

@@ -3,36 +3,5 @@ import { ModelConfigManager } from './model-config-manager';
 import { type GLOBAL_ENV_KEYS, type MODEL_ENV_KEYS } from './types';
 export declare const globalModelConfigManager: ModelConfigManager;
 export declare const globalConfigManager: 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 declare function getCurrentTime(device?: DeviceWithTimestamp, useDeviceTimestamp?: boolean): Promise<number>;
 export declare const getPreferredLanguage: () => string;
 export declare const overrideAIConfig: (newConfig: Partial<Record<(typeof GLOBAL_ENV_KEYS)[number] | (typeof MODEL_ENV_KEYS)[number], string>>, extendMode?: boolean) => void;

package/dist/types/extractor/index.d.ts

@@ -28,5 +28,5 @@ export { extractTextWithPosition as webExtractTextWithPosition } from './web-ext
 export { extractTreeNode as webExtractNodeTree } from './web-extractor';
 export { extractTreeNodeAsString as webExtractNodeTreeAsString } from './web-extractor';
 export { getXpathsByPoint, getXpathsById, getNodeInfoByXpath, getElementInfoByXpath, getElementXpath, } from './locator';
-export { generateElementByRect } from './dom-util';
+export { generateElementByPoint, generateElementByRect } from './dom-util';
 export { isNotContainerElement } from './dom-util';

package/dist/types/img/index.d.ts

@@ -1,3 +1,3 @@
-export { imageInfoOfBase64, isValidPNGImageBuffer, isValidJPEGImageBuffer, isValidImageBuffer, } from './info';
+export { imageInfoOfBase64, isValidPNGImageBuffer, isValidJPEGImageBuffer, isValidImageBuffer, validateScreenshotBuffer, type ValidateScreenshotBufferOptions, } from './info';
 export { resizeAndConvertImgBuffer, resizeImgBase64, zoomForGPT4o, saveBase64Image, paddingToMatchBlockByBase64, cropByRect, scaleImage, localImg2Base64, httpImg2Base64, preProcessImageUrl, parseBase64, createImgBase64ByFormat, } from './transform';
 export { processImageElementInfo, compositeElementInfoImg, annotateRects, } from './box-select';

package/dist/types/img/info.d.ts

@@ -27,3 +27,8 @@ export declare function isValidJPEGImageBuffer(buffer: Buffer): boolean;
  * @returns true if the Buffer is a valid PNG or JPEG image, otherwise false
  */
 export declare function isValidImageBuffer(buffer: Buffer): boolean;
+export interface ValidateScreenshotBufferOptions {
+    label: string;
+    minBufferSize?: number;
+}
+export declare function validateScreenshotBuffer(screenshotBuffer: Buffer | undefined, { label, minBufferSize }: ValidateScreenshotBufferOptions): asserts screenshotBuffer is Buffer;

package/dist/types/key-alias-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal-only helpers for CLI/MCP argument key aliasing.
+ * Not re-exported from the package entry point — keep consumers within
+ * `cli/` and `mcp/`.
+ */
+export declare function kebabToCamel(str: string): string;
+export declare function camelToKebab(str: string): string;
+export declare function getKeyAliases(key: string): string[];
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/types/mcp/base-tools.d.ts

@@ -1,13 +1,53 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { BaseAgent, BaseDevice, IMidsceneTools, ToolDefinition } from './types';
+import type { z } from 'zod';
+import { type CliReportSession } from './cli-report-session';
+import type { BaseAgent, BaseDevice, IMidsceneTools, ToolCliMetadata, ToolDefinition, ToolSchema } from './types';
 /**
- * Base class for platform-specific MCP tools
- * Generic type TAgent allows subclasses to use their specific agent types
+ * Declarative description of a platform's agent init args.
+ * Collapses the `extractAgentInitParam` / `sanitizeToolArgs` /
+ * `getAgentInitArgSchema` trio into a single data declaration.
  */
-export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent> implements IMidsceneTools {
+export interface InitArgSpec<TInitParam> {
+    /** Arg namespace, e.g. `android`, `ios`. */
+    namespace: string;
+    /** Zod shape describing the init args. Field names drive the MCP schema. */
+    shape: Record<string, z.ZodTypeAny>;
+    /**
+     * Optional CLI presentation hints. These affect `--help` output for
+     * single-platform CLIs but do not alter MCP/YAML protocol keys.
+     */
+    cli?: {
+        /** Prefer bare `--device-id`-style options in platform CLI help output. */
+        preferBareKeys?: boolean;
+        /** Override the displayed option name for specific init arg fields. */
+        preferredNames?: Record<string, string>;
+    };
+    /**
+     * Adapt extracted namespaced args into the concrete `TInitParam` passed to
+     * `ensureAgent`. Defaults to returning the raw extracted record.
+     */
+    adapt?: (extracted: Record<string, unknown> | undefined) => TInitParam | undefined;
+}
+/**
+ * Base class for platform-specific MCP tools.
+ * @typeParam TAgent - Platform-specific agent type.
+ * @typeParam TInitParam - Platform-specific init parameter consumed by
+ *   `ensureAgent`. Defaults to `undefined` for platforms that take no args.
+ */
+export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent, TInitParam = unknown> implements IMidsceneTools {
     protected mcpServer?: McpServer;
     protected agent?: TAgent;
     protected toolDefinitions: ToolDefinition[];
+    /**
+     * Declarative init-arg spec. Subclasses that accept CLI/MCP init args should
+     * set this once and get `extractAgentInitParam` / `sanitizeToolArgs` /
+     * `getAgentInitArgSchema` auto-implemented.
+     *
+     * Declared with `declare` so that TS doesn't emit an `Object.defineProperty`
+     * for this field on the base constructor, which would otherwise overwrite
+     * a subclass field initializer under `useDefineForClassFields`.
+     */
+    protected readonly initArgSpec?: InitArgSpec<TInitParam>;
     /**
      * Ensure agent is initialized and ready for use.
      * Must be implemented by subclasses to create platform-specific agent.
@@ -15,11 +55,40 @@ export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseA
      * @returns Promise resolving to initialized agent instance
      * @throws Error if agent initialization fails
      */
-    protected abstract ensureAgent(initParam?: string): Promise<TAgent>;
+    protected abstract ensureAgent(initParam?: TInitParam): Promise<TAgent>;
+    private getInitArgKeys;
+    /**
+     * Extract a platform-specific agent init parameter from CLI/MCP tool args.
+     */
+    protected extractAgentInitParam(args: Record<string, unknown>): TInitParam | undefined;
+    /**
+     * Remove platform-specific init args before dispatching a tool payload to the action itself.
+     */
+    protected sanitizeToolArgs(args: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Expose platform-specific init args on action/common tool schemas.
+     */
+    protected getAgentInitArgSchema(): ToolSchema;
+    /**
+     * Expose CLI-only metadata for platform init args so single-platform help can
+     * show ergonomic bare flags while the underlying schema stays namespaced.
+     * When `preferBareKeys` is enabled, single-platform CLIs only accept the
+     * bare spellings; namespaced dotted spellings remain available through the
+     * MCP/YAML schema instead of the platform CLI surface.
+     */
+    protected getAgentInitArgCliMetadata(): ToolCliMetadata | undefined;
     /**
      * Optional: prepare platform-specific tools (e.g., device connection)
      */
     protected preparePlatformTools(): ToolDefinition[];
+    protected getCliReportSessionName(): string | undefined;
+    protected createNewCliReportSession(targetIdentity?: string): CliReportSession | undefined;
+    protected commitCliReportSession(session?: CliReportSession): void;
+    protected readCliReportFileName(): string | undefined;
+    protected readCliReportAgentOptions(): {
+        reportFileName: string;
+        reportAttributes: Record<string, string>;
+    } | undefined;
     /**
      * Must be implemented by subclasses to create a temporary device instance
      * This allows getting real actionSpace without connecting to device

package/dist/types/mcp/cli-report-session.d.ts

@@ -0,0 +1,12 @@
+export interface CliReportSession {
+    version: 1;
+    sessionName: string;
+    targetIdentity?: string;
+    reportFileName: string;
+    reportPath: string;
+    createdAt: number;
+}
+export declare function generateCliReportSession(sessionName: string, targetIdentity?: string): CliReportSession;
+export declare function writeCliReportSession(session: CliReportSession): void;
+export declare function createCliReportSession(sessionName: string, targetIdentity?: string): CliReportSession;
+export declare function readCliReportSession(sessionName: string): CliReportSession | undefined;

package/dist/types/mcp/error-formatter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function getErrorMessage(error: unknown): string;

package/dist/types/mcp/index.d.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/dist/types/mcp/init-arg-utils.d.ts

@@ -0,0 +1,13 @@
+import type { z } from 'zod';
+import type { ToolSchema } from './types';
+export declare function extractNamespacedArgs<TFieldName extends string, TArgs extends Record<string, unknown> = Record<string, unknown>>(args: Record<string, unknown>, namespace: string, keys: readonly TFieldName[]): TArgs | undefined;
+export declare function sanitizeNamespacedArgs(args: Record<string, unknown>, namespace: string, keys: readonly string[]): Record<string, unknown>;
+/**
+ * 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 declare function createNamespacedInitArgSchema(namespace: string, shape: Record<string, z.ZodTypeAny>): ToolSchema;

package/dist/types/mcp/inject-report-html-plugin.d.ts

@@ -2,12 +2,12 @@ interface RslibPluginApi {
     onAfterBuild: (callback: () => void) => void;
 }
 /**
- * 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)
  */

package/dist/types/mcp/launcher-helper.d.ts

@@ -9,7 +9,7 @@ export interface LaunchMCPServerOptions extends HttpLaunchOptions {
     verbose?: boolean;
 }
 /**
- * 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;
@@ -58,8 +58,8 @@ export interface MCPServerLauncherConfig<AgentType extends GenericAgent = Generi
  *
  * @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/dist/types/mcp/tool-generator.d.ts

@@ -1,10 +1,10 @@
-import type { ActionSpaceItem, BaseAgent, ToolDefinition } from './types';
+import type { ActionSpaceItem, BaseAgent, ToolCliMetadata, ToolDefinition, ToolSchema } from './types';
 /**
  * Converts DeviceAction from actionSpace into MCP ToolDefinition
  * This is the core logic that removes need for hardcoded tool definitions
  */
-export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: () => Promise<BaseAgent>): ToolDefinition[];
+export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, sanitizeArgs?: (args: Record<string, unknown>) => Record<string, unknown>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata): ToolDefinition[];
 /**
  * Generate common tools (screenshot, act)
  */
-export declare function generateCommonTools(getAgent: () => Promise<BaseAgent>): ToolDefinition[];
+export declare function generateCommonTools(getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata): ToolDefinition[];

package/dist/types/mcp/types.d.ts

@@ -49,6 +49,13 @@ export type ToolHandler<T = Record<string, unknown>> = (args: T) => Promise<Tool
  * Tool schema type using Zod
  */
 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
  */
@@ -57,6 +64,7 @@ export interface ToolDefinition<T = Record<string, unknown>> {
     description: string;
     schema: ToolSchema;
     handler: ToolHandler<T>;
+    cli?: ToolCliMetadata;
 }
 /**
  * Tool type for mcpKitForAgent return value
@@ -86,6 +94,7 @@ export interface BaseAgent {
     callActionInActionSpace?: (actionName: string, params?: unknown) => Promise<unknown>;
     aiAction?: (description: string, params?: Record<string, unknown>) => Promise<unknown>;
     aiWaitFor?: (assertion: string, options: Record<string, unknown>) => Promise<unknown>;
+    aiAssert?: (assertion: string, msg?: string, options?: Record<string, unknown>) => Promise<unknown>;
 }
 /**
  * Base device interface for temporary device instances

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiscene/shared",
-  "version": "8.0.1",
+  "version": "8.0.3",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/cli/cli-args.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { getKeyAliases } from '../key-alias-utils';
+import type { ToolCliOption, ToolDefinition } from '../mcp/types';
+
+export function parseValue(raw: string): unknown {
+  if (raw.startsWith('{') || raw.startsWith('[')) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      // Not valid JSON, treat as string below
+    }
+  }
+
+  if (/^-?\d+(\.\d+)?$/.test(raw)) {
+    return Number(raw);
+  }
+
+  return raw;
+}
+
+function walkCliArgs(
+  args: string[],
+  setArgValue: (key: string, value: unknown) => void,
+): void {
+  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) {
+      setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+    } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+      i++;
+      setArgValue(body, parseValue(args[i]));
+    } else {
+      setArgValue(body, true);
+    }
+  }
+}
+
+export function parseCliArgs(args: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  walkCliArgs(args, (key, value) => {
+    result[key] = value;
+  });
+
+  return result;
+}
+
+function formatCliOptionName(name: string): string {
+  return `--${name}`;
+}
+
+export function getCliOptionDisplay(
+  key: string,
+  cliOption?: ToolCliOption,
+): { label: string; aliases: string[] } {
+  const label = formatCliOptionName(cliOption?.preferredName ?? key);
+  const aliases = [...new Set(cliOption?.aliases ?? [])]
+    .map((alias) => formatCliOptionName(alias))
+    .filter((alias) => alias !== label);
+
+  return { label, aliases };
+}
+
+function getAcceptedCliOptionNames(
+  key: string,
+  cliOption?: ToolCliOption,
+): string[] {
+  return [
+    ...new Set(
+      cliOption
+        ? [cliOption.preferredName ?? key, ...(cliOption.aliases ?? [])]
+        : [key, ...getKeyAliases(key)],
+    ),
+  ];
+}
+
+function toOptionalCliSchemaField(field: unknown): z.ZodTypeAny {
+  if (
+    typeof field === 'object' &&
+    field !== null &&
+    typeof (field as z.ZodTypeAny).optional === 'function'
+  ) {
+    return (field as z.ZodTypeAny).optional();
+  }
+
+  const description =
+    typeof field === 'object' &&
+    field !== null &&
+    'description' in field &&
+    typeof (field as { description?: unknown }).description === 'string'
+      ? (field as { description: string }).description
+      : undefined;
+  return description ? z.any().describe(description) : z.any();
+}
+
+function buildCliArgSchema(def: ToolDefinition): Record<string, z.ZodTypeAny> {
+  return Object.fromEntries(
+    Object.entries(def.schema).flatMap(([key, zodType]) =>
+      getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey) => [
+        cliKey,
+        toOptionalCliSchemaField(zodType),
+      ]),
+    ),
+  );
+}
+
+function buildDisallowedCliSpellings(def: ToolDefinition): Set<string> {
+  const disallowedSpellings = new Set<string>();
+
+  for (const [key] of Object.entries(def.schema)) {
+    const cliOption = def.cli?.options?.[key];
+    const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
+    const knownSpellings = new Set<string>([
+      key,
+      ...getKeyAliases(key),
+      ...(cliOption?.preferredName
+        ? getKeyAliases(cliOption.preferredName)
+        : []),
+      ...(cliOption?.aliases ?? []),
+    ]);
+
+    for (const spelling of knownSpellings) {
+      if (!acceptedNames.has(spelling)) {
+        disallowedSpellings.add(spelling);
+      }
+    }
+  }
+
+  return disallowedSpellings;
+}
+
+export function formatCliValidationError(
+  scriptName: string,
+  commandName: string,
+  def: ToolDefinition,
+  rawArgs: Record<string, unknown>,
+): string | undefined {
+  if (Object.keys(def.schema).length === 0) {
+    return undefined;
+  }
+
+  const cliSchema = z.object(buildCliArgSchema(def)).strict();
+  const parsed = cliSchema.safeParse(rawArgs);
+  if (parsed.success) {
+    return undefined;
+  }
+
+  const disallowedSpellings = buildDisallowedCliSpellings(def);
+  const unknownKeys = parsed.error.issues.flatMap((issue) =>
+    issue.code === 'unrecognized_keys' ? issue.keys : [],
+  );
+
+  if (unknownKeys.length > 0) {
+    return unknownKeys
+      .map((key) => {
+        if (disallowedSpellings.has(key)) {
+          return `Unsupported option "--${key}" for ${scriptName} ${commandName}.`;
+        }
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+      })
+      .join('\n');
+  }
+
+  const [issue] = parsed.error.issues;
+  const optionName =
+    typeof issue?.path[0] === 'string' ? `--${issue.path[0]}` : 'CLI arguments';
+  return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
+}

package/src/cli/cli-error.ts

@@ -0,0 +1,24 @@
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public exitCode = 1,
+  ) {
+    super(message);
+  }
+}
+
+export function reportCLIError(
+  error: unknown,
+  log: (
+    message?: unknown,
+    ...optionalParams: unknown[]
+  ) => void = console.error,
+): number {
+  if (error instanceof CLIError) {
+    log(error.message);
+    return error.exitCode;
+  }
+
+  log(error);
+  return 1;
+}