@aiscene/shared 8.0.1 → 8.0.3

package/src/mcp/base-tools.ts

@@ -1,6 +1,19 @@
-import { parseBase64 } from '../img';
-import { getDebug } from '../logger';
+import { parseBase64 } from '@aiscene/shared/img';
+import { getDebug } from '@aiscene/shared/logger';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+import { camelToKebab, getKeyAliases } from '../key-alias-utils';
+import {
+  type CliReportSession,
+  generateCliReportSession,
+  readCliReportSession,
+  writeCliReportSession,
+} from './cli-report-session';
+import {
+  createNamespacedInitArgSchema,
+  extractNamespacedArgs,
+  sanitizeNamespacedArgs,
+} from './init-arg-utils';
 import {
   generateCommonTools,
   generateToolsFromActionSpace,
@@ -10,22 +23,68 @@ import type {
   BaseAgent,
   BaseDevice,
   IMidsceneTools,
+  ToolCliMetadata,
   ToolDefinition,
+  ToolSchema,
 } from './types';
 
 const debug = getDebug('mcp:base-tools');
 
 /**
- * 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 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 abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent>
-  implements IMidsceneTools
+export 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 declare readonly initArgSpec?: InitArgSpec<TInitParam>;
+
   /**
    * Ensure agent is initialized and ready for use.
    * Must be implemented by subclasses to create platform-specific agent.
@@ -33,7 +92,102 @@ export abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent>
    * @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(): readonly string[] {
+    return this.initArgSpec ? Object.keys(this.initArgSpec.shape) : [];
+  }
+
+  /**
+   * Extract a platform-specific agent init parameter from CLI/MCP tool args.
+   */
+  protected extractAgentInitParam(
+    args: Record<string, unknown>,
+  ): TInitParam | undefined {
+    if (!this.initArgSpec) {
+      return undefined;
+    }
+    const extracted = extractNamespacedArgs(
+      args,
+      this.initArgSpec.namespace,
+      this.getInitArgKeys(),
+    );
+    if (this.initArgSpec.adapt) {
+      return this.initArgSpec.adapt(extracted);
+    }
+    return extracted as 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> {
+    if (!this.initArgSpec) {
+      return args;
+    }
+    return sanitizeNamespacedArgs(
+      args,
+      this.initArgSpec.namespace,
+      this.getInitArgKeys(),
+    );
+  }
+
+  /**
+   * Expose platform-specific init args on action/common tool schemas.
+   */
+  protected getAgentInitArgSchema(): ToolSchema {
+    if (!this.initArgSpec) {
+      return {};
+    }
+    return createNamespacedInitArgSchema(
+      this.initArgSpec.namespace,
+      this.initArgSpec.shape,
+    );
+  }
+
+  /**
+   * 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 {
+    if (!this.initArgSpec?.cli) {
+      return undefined;
+    }
+
+    const options = Object.fromEntries(
+      this.getInitArgKeys().map((key) => {
+        const canonicalKey = `${this.initArgSpec!.namespace}.${key}`;
+        const preferredName =
+          this.initArgSpec!.cli?.preferredNames?.[key] ??
+          (this.initArgSpec!.cli?.preferBareKeys
+            ? camelToKebab(key)
+            : canonicalKey);
+
+        const acceptedNames = new Set<string>([
+          preferredName,
+          ...(this.initArgSpec!.cli?.preferBareKeys
+            ? getKeyAliases(key)
+            : getKeyAliases(canonicalKey)),
+        ]);
+        acceptedNames.delete(preferredName);
+
+        return [
+          canonicalKey,
+          {
+            preferredName,
+            aliases: [...acceptedNames],
+          },
+        ];
+      }),
+    );
+
+    return { options };
+  }
 
   /**
    * Optional: prepare platform-specific tools (e.g., device connection)
@@ -42,6 +196,52 @@ export abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent>
     return [];
   }
 
+  protected getCliReportSessionName(): string | undefined {
+    return undefined;
+  }
+
+  protected createNewCliReportSession(
+    targetIdentity?: string,
+  ): CliReportSession | undefined {
+    const sessionName = this.getCliReportSessionName();
+    if (!sessionName) {
+      return undefined;
+    }
+    return generateCliReportSession(sessionName, targetIdentity);
+  }
+
+  protected commitCliReportSession(session?: CliReportSession): void {
+    if (session) {
+      writeCliReportSession(session);
+    }
+  }
+
+  protected readCliReportFileName(): string | undefined {
+    const sessionName = this.getCliReportSessionName();
+    if (!sessionName) {
+      return undefined;
+    }
+    return readCliReportSession(sessionName)?.reportFileName;
+  }
+
+  protected readCliReportAgentOptions():
+    | {
+        reportFileName: string;
+        reportAttributes: Record<string, string>;
+      }
+    | undefined {
+    const reportFileName = this.readCliReportFileName();
+    if (!reportFileName) {
+      return undefined;
+    }
+    return {
+      reportFileName,
+      reportAttributes: {
+        'data-group-id': reportFileName,
+      },
+    };
+  }
+
   /**
    * Must be implemented by subclasses to create a temporary device instance
    * This allows getting real actionSpace without connecting to device
@@ -83,13 +283,20 @@ export abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent>
     }
 
     // 3. Generate tools from action space (core innovation)
-    const actionTools = generateToolsFromActionSpace(actionSpace, () =>
-      this.ensureAgent(),
+    const actionTools = generateToolsFromActionSpace(
+      actionSpace,
+      (args = {}) => this.ensureAgent(this.extractAgentInitParam(args)),
+      (args = {}) => this.sanitizeToolArgs(args),
+      this.getAgentInitArgSchema(),
+      this.getAgentInitArgCliMetadata(),
     );
 
     // 4. Add common tools (screenshot, waitFor)
-    const commonTools = generateCommonTools(() => this.ensureAgent());
-
+    const commonTools = generateCommonTools(
+      (args = {}) => this.ensureAgent(this.extractAgentInitParam(args)),
+      this.getAgentInitArgSchema(),
+      this.getAgentInitArgCliMetadata(),
+    );
     this.toolDefinitions.push(...actionTools, ...commonTools);
 
     debug('Total tools prepared:', this.toolDefinitions.length);

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';
  *