@aiscene/shared 8.0.3 → 8.0.4

package/dist/lib/recorder.js

@@ -0,0 +1,307 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS: ()=>DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS,
+    buildMidsceneRecorderActionSummary: ()=>buildMidsceneRecorderActionSummary,
+    buildMidsceneRecorderReplayInstruction: ()=>buildMidsceneRecorderReplayInstruction,
+    createMidsceneRecorderMarkdownScreenshotAssets: ()=>createMidsceneRecorderMarkdownScreenshotAssets,
+    getMidsceneRecorderEventDescription: ()=>getMidsceneRecorderEventDescription,
+    getMidsceneRecorderScreenshotsForLLM: ()=>getMidsceneRecorderScreenshotsForLLM,
+    getMidsceneRecorderSemantic: ()=>getMidsceneRecorderSemantic,
+    sanitizeMidsceneRecorderFileName: ()=>sanitizeMidsceneRecorderFileName,
+    stringifyMidsceneRecorderTargetBlock: ()=>stringifyMidsceneRecorderTargetBlock
+});
+const DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS = 20;
+function isMidsceneRecorderPendingDescription(value) {
+    return value?.trim() === 'AI is analyzing element...';
+}
+function getMidsceneRecorderSemantic(event) {
+    return event.semantic;
+}
+function getRecorderPointerActionVerb(actionType) {
+    switch(actionType){
+        case 'Tap':
+            return 'Tap';
+        case 'DoubleClick':
+            return 'Double click';
+        case 'LongPress':
+            return 'Long press';
+        case 'RightClick':
+            return 'Right click';
+        default:
+            return 'Click';
+    }
+}
+function getRecorderDragActionVerb(actionType) {
+    switch(actionType){
+        case 'Swipe':
+            return 'Swipe';
+        case 'DragAndDrop':
+            return 'Drag';
+        default:
+            return 'Drag';
+    }
+}
+function buildMidsceneRecorderReplayInstruction(event, elementDescription) {
+    switch(event.type){
+        case 'navigation':
+            if ('Stop' === event.actionType) return 'Stop loading the current page.';
+            if ('GoBack' === event.actionType) return 'Go back in the browser.';
+            if ('GoForward' === event.actionType) return 'Go forward in the browser.';
+            if ('Reload' === event.actionType) return 'Reload the current page.';
+            if ('NavigationChanged' === event.actionType && event.url) return `Wait for navigation to complete at \`${event.url}\`.`;
+            return event.url ? `Navigate to \`${event.url}\`.` : `Navigate using ${elementDescription}.`;
+        case 'scroll':
+            return event.scrollDestinationDescription ? `Scroll the page/region with description "${elementDescription}" by value "${event.value || 'down'}" until "${event.scrollDestinationDescription}" is visible.` : `Scroll the page/region with description "${elementDescription}" by value "${event.value || 'down'}".`;
+        case 'drag':
+            {
+                const verb = getRecorderDragActionVerb(event.actionType);
+                return `${verb} through the area described as "${elementDescription}".`;
+            }
+        case 'input':
+            return `Input "${event.value || ''}" into the element described as "${elementDescription}".`;
+        case 'keydown':
+            return `Press "${event.value || 'the recorded key'}" on the element described as "${elementDescription}".`;
+        default:
+            {
+                const verb = getRecorderPointerActionVerb(event.actionType);
+                if ('Long press' === verb) return `${verb} the element described as "${elementDescription}".`;
+                return `${verb} on the element described as "${elementDescription}".`;
+            }
+    }
+}
+function buildMidsceneRecorderActionSummary(event, elementDescription) {
+    switch(event.type){
+        case 'navigation':
+            if ('Stop' === event.actionType) return 'Stop page loading';
+            if ('GoBack' === event.actionType) return 'Go back';
+            if ('GoForward' === event.actionType) return 'Go forward';
+            if ('Reload' === event.actionType) return 'Reload page';
+            if ('NavigationChanged' === event.actionType && event.url) return `Wait for navigation to complete at ${event.url}`;
+            return event.url ? `Navigate to ${event.url}` : 'Navigate';
+        case 'scroll':
+            return event.scrollDestinationDescription ? `Scroll ${elementDescription} toward ${event.scrollDestinationDescription}` : `Scroll ${elementDescription}`;
+        case 'drag':
+            return `${getRecorderDragActionVerb(event.actionType)} ${elementDescription}`;
+        case 'input':
+            return `Input into ${elementDescription}`;
+        case 'keydown':
+            return `Press ${event.value || 'key'} on ${elementDescription}`;
+        default:
+            return `${getRecorderPointerActionVerb(event.actionType)} ${elementDescription}`;
+    }
+}
+function getMidsceneRecorderEventDescription(event) {
+    const semantic = getMidsceneRecorderSemantic(event);
+    if (semantic?.actionSummary && !isMidsceneRecorderPendingDescription(semantic.actionSummary)) return semantic.actionSummary;
+    if (semantic?.elementDescription && !isMidsceneRecorderPendingDescription(semantic.elementDescription)) return semantic.elementDescription;
+    if (semantic?.replayInstruction && !isMidsceneRecorderPendingDescription(semantic.replayInstruction)) return semantic.replayInstruction;
+    if ('navigation' === event.type && event.url) return `Navigate to ${event.url}`;
+    if (event.value) return event.actionType ? `${event.actionType} ${event.value}` : event.value;
+    if (event.elementRect?.x !== void 0 && event.elementRect?.y !== void 0) {
+        const prefix = event.actionType || event.type;
+        return `${prefix} (${Math.round(event.elementRect.x)}, ${Math.round(event.elementRect.y)})`;
+    }
+    return event.actionType || event.type;
+}
+function getMidsceneRecorderScreenshotsForLLM(events, maxScreenshots = 1) {
+    return selectRecorderScreenshotCandidates(getRecorderScreenshotCandidates(events), maxScreenshots).map((candidate)=>candidate.screenshot);
+}
+function sanitizeMidsceneRecorderFileName(value) {
+    return value.trim().replace(/[\\/:*?"<>|]+/g, '-').replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase() || 'midscene-recording';
+}
+function normalizeMarkdownAssetBaseDir(baseDir) {
+    const value = (baseDir || './screenshots').replace(/\/+$/g, '');
+    if (value.startsWith('./') || value.startsWith('../')) return value;
+    return `./${value}`;
+}
+function padEventIndex(index) {
+    return String(index + 1).padStart(3, '0');
+}
+function parseScreenshotDataUrl(value) {
+    const dataUrlMatch = value.match(/^data:(image\/[a-zA-Z0-9.+-]+);base64,(.+)$/);
+    if (dataUrlMatch) {
+        const mimeType = dataUrlMatch[1];
+        const extension = mimeType.includes('jpeg') ? 'jpg' : mimeType.split('/')[1]?.replace(/[^a-zA-Z0-9]/g, '') || 'png';
+        return {
+            dataUrl: value,
+            base64Data: dataUrlMatch[2],
+            mimeType,
+            extension
+        };
+    }
+    if (/^[a-zA-Z0-9+/=\s]+$/.test(value) && value.trim().length > 0) {
+        const base64Data = value.replace(/\s+/g, '');
+        return {
+            dataUrl: `data:image/png;base64,${base64Data}`,
+            base64Data,
+            mimeType: 'image/png',
+            extension: 'png'
+        };
+    }
+}
+function getRecorderEventScreenshot(event) {
+    return event.screenshotWithBox || event.screenshotAfter || event.screenshotBefore;
+}
+function hasCoordinateFallback(event) {
+    const semantic = getMidsceneRecorderSemantic(event);
+    return !semantic?.elementDescription && event.elementRect?.x !== void 0 && event.elementRect?.y !== void 0;
+}
+function shouldIncludeMarkdownScreenshot(event, eventIndex, lastEventIndex) {
+    const semantic = getMidsceneRecorderSemantic(event);
+    return 0 === eventIndex || eventIndex === lastEventIndex || 'navigation' === event.type || 'scroll' === event.type || 'input' === event.type || Boolean(event.screenshotWithBox) || !semantic?.elementDescription || hasCoordinateFallback(event);
+}
+function getRecorderScreenshotCandidatePriority(candidate, firstEventIndex, lastEventIndex) {
+    const event = candidate.event;
+    let priority = 0;
+    if (candidate.eventIndex === firstEventIndex) priority += 100;
+    if (candidate.eventIndex === lastEventIndex) priority += 95;
+    if ('navigation' === event.type) priority += 80;
+    if (event.screenshotWithBox) priority += 70;
+    const semantic = getMidsceneRecorderSemantic(event);
+    if (semantic?.source === 'heuristic' || semantic?.confidence === 'low' || semantic?.error) priority += 60;
+    if ('input' === event.type || 'scroll' === event.type) priority += 40;
+    if (!semantic?.elementDescription || hasCoordinateFallback(event)) priority += 30;
+    return priority;
+}
+function selectEvenlyDistributedCandidates(candidates, count) {
+    if (count <= 0) return [];
+    if (candidates.length <= count) return candidates;
+    if (1 === count) return [
+        candidates[Math.floor((candidates.length - 1) / 2)]
+    ];
+    return Array.from({
+        length: count
+    }, (_, index)=>{
+        const candidateIndex = Math.round(index * (candidates.length - 1) / (count - 1));
+        return candidates[candidateIndex];
+    });
+}
+function selectRecorderScreenshotCandidates(candidates, maxScreenshots) {
+    if (maxScreenshots <= 0 || 0 === candidates.length) return [];
+    if (candidates.length <= maxScreenshots) return candidates;
+    const selected = new Map();
+    const firstEventIndex = candidates[0].eventIndex;
+    const lastEventIndex = candidates[candidates.length - 1].eventIndex;
+    const addCandidate = (candidate)=>{
+        if (!candidate || selected.size >= maxScreenshots) return;
+        selected.set(candidate.eventIndex, candidate);
+    };
+    const addEvenly = (pool)=>{
+        const remaining = maxScreenshots - selected.size;
+        if (remaining <= 0) return;
+        const unselected = pool.filter((candidate)=>!selected.has(candidate.eventIndex));
+        for (const candidate of selectEvenlyDistributedCandidates(unselected, remaining))addCandidate(candidate);
+    };
+    addCandidate(candidates[0]);
+    addCandidate(candidates[candidates.length - 1]);
+    addEvenly(candidates.filter((candidate)=>getRecorderScreenshotCandidatePriority(candidate, firstEventIndex, lastEventIndex) >= 60));
+    addEvenly(candidates.filter((candidate)=>getRecorderScreenshotCandidatePriority(candidate, firstEventIndex, lastEventIndex) >= 40));
+    addEvenly(candidates);
+    return Array.from(selected.values()).sort((left, right)=>left.eventIndex - right.eventIndex);
+}
+function getRecorderScreenshotCandidates(events) {
+    const candidates = [];
+    const seenScreenshots = new Set();
+    const lastEventIndex = events.length - 1;
+    for(let eventIndex = 0; eventIndex < events.length; eventIndex += 1){
+        const event = events[eventIndex];
+        if (!shouldIncludeMarkdownScreenshot(event, eventIndex, lastEventIndex)) continue;
+        const screenshot = getRecorderEventScreenshot(event);
+        if (!(!screenshot || seenScreenshots.has(screenshot))) {
+            seenScreenshots.add(screenshot);
+            candidates.push({
+                event,
+                eventIndex,
+                screenshot
+            });
+        }
+    }
+    return candidates;
+}
+function createMidsceneRecorderMarkdownScreenshotAssets(events, options = {}) {
+    const baseDir = normalizeMarkdownAssetBaseDir(options.baseDir);
+    const maxScreenshots = options.maxScreenshots ?? DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS;
+    const candidates = [];
+    for (const candidate of getRecorderScreenshotCandidates(events)){
+        const parsedScreenshot = parseScreenshotDataUrl(candidate.screenshot);
+        if (parsedScreenshot) candidates.push({
+            ...candidate,
+            parsedScreenshot
+        });
+    }
+    return selectRecorderScreenshotCandidates(candidates, maxScreenshots).map(({ event, eventIndex, parsedScreenshot })=>{
+        const safeType = event.type.replace(/[^a-zA-Z0-9-]/g, '-');
+        const fileName = `event-${padEventIndex(eventIndex)}-${safeType}.${parsedScreenshot.extension}`;
+        return {
+            eventIndex,
+            eventHashId: event.hashId,
+            eventType: event.type,
+            relativePath: `${baseDir}/${fileName}`,
+            dataUrl: parsedScreenshot.dataUrl,
+            base64Data: parsedScreenshot.base64Data,
+            mimeType: parsedScreenshot.mimeType
+        };
+    });
+}
+function scalarToYaml(value) {
+    return JSON.stringify(value);
+}
+function stringifyMidsceneRecorderTargetBlock(target) {
+    const lines = [
+        `${target.platformId}:`
+    ];
+    const values = Object.entries(target.values);
+    if (0 === values.length) {
+        lines.push('  {}');
+        return lines.join('\n');
+    }
+    for (const [key, value] of values)lines.push(`  ${key}: ${scalarToYaml(value)}`);
+    return lines.join('\n');
+}
+exports.DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS = __webpack_exports__.DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS;
+exports.buildMidsceneRecorderActionSummary = __webpack_exports__.buildMidsceneRecorderActionSummary;
+exports.buildMidsceneRecorderReplayInstruction = __webpack_exports__.buildMidsceneRecorderReplayInstruction;
+exports.createMidsceneRecorderMarkdownScreenshotAssets = __webpack_exports__.createMidsceneRecorderMarkdownScreenshotAssets;
+exports.getMidsceneRecorderEventDescription = __webpack_exports__.getMidsceneRecorderEventDescription;
+exports.getMidsceneRecorderScreenshotsForLLM = __webpack_exports__.getMidsceneRecorderScreenshotsForLLM;
+exports.getMidsceneRecorderSemantic = __webpack_exports__.getMidsceneRecorderSemantic;
+exports.sanitizeMidsceneRecorderFileName = __webpack_exports__.sanitizeMidsceneRecorderFileName;
+exports.stringifyMidsceneRecorderTargetBlock = __webpack_exports__.stringifyMidsceneRecorderTargetBlock;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS",
+    "buildMidsceneRecorderActionSummary",
+    "buildMidsceneRecorderReplayInstruction",
+    "createMidsceneRecorderMarkdownScreenshotAssets",
+    "getMidsceneRecorderEventDescription",
+    "getMidsceneRecorderScreenshotsForLLM",
+    "getMidsceneRecorderSemantic",
+    "sanitizeMidsceneRecorderFileName",
+    "stringifyMidsceneRecorderTargetBlock"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/types/agent-tools/agent-behavior-init-args.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export interface AgentBehaviorInitArgs {
+    aiActContext?: string;
+    aiActionContext?: string;
+    replanningCycleLimit?: number;
+    waitAfterAction?: number;
+    screenshotShrinkFactor?: number;
+}
+export declare const agentBehaviorInitArgShape: {
+    aiActContext: z.ZodOptional<z.ZodString>;
+    replanningCycleLimit: z.ZodOptional<z.ZodNumber>;
+    waitAfterAction: z.ZodOptional<z.ZodNumber>;
+    screenshotShrinkFactor: z.ZodOptional<z.ZodNumber>;
+};
+export declare function extractAgentBehaviorInitArgs(extracted: Partial<AgentBehaviorInitArgs> | undefined): AgentBehaviorInitArgs | undefined;
+export declare function getAgentInitArgsSignature(initArgs: object | undefined): string | undefined;
+export declare function shouldRebuildAgentForInitArgs(currentSignature: string | undefined, nextSignature: string | undefined): boolean;

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

@@ -0,0 +1,158 @@
+import type { z } from 'zod';
+import { type CliReportSession } from './cli-report-session';
+import { type ToolDefaults } from './tool-defaults';
+import type { BaseAgent, BaseDevice, IMidsceneTools, ToolCliMetadata, ToolDefinition, ToolSchema } from './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 tool schema. */
+    shape: Record<string, z.ZodTypeAny>;
+    /**
+     * Optional CLI presentation hints. These affect `--help` output for
+     * single-platform CLIs but do not alter 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 Midscene 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 agent?: TAgent;
+    protected toolDefinitions: ToolDefinition[];
+    /**
+     * Default options injected into every generated tool call (e.g. forced deep
+     * locate / deep think). Set from startup/CLI behavior flags before
+     * `initTools()` so they are baked into the generated tool handlers.
+     * See https://github.com/web-infra-dev/midscene/issues/2446.
+     */
+    protected toolDefaults: ToolDefaults;
+    /**
+     * Declarative init-arg spec. Subclasses that accept CLI 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.
+     * @param initParam Optional initialization parameter (platform-specific, e.g., URL, device ID)
+     * @returns Promise resolving to initialized agent instance
+     * @throws Error if agent initialization fails
+     */
+    protected abstract ensureAgent(initParam?: TInitParam): Promise<TAgent>;
+    private getInitArgKeys;
+    /**
+     * Extract a platform-specific agent init parameter from CLI 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
+     * 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
+     */
+    protected abstract createTemporaryDevice(): BaseDevice;
+    /**
+     * Initialize all tools by querying actionSpace
+     * Uses two-layer fallback strategy:
+     * 1. Try to get actionSpace from connected agent (if available)
+     * 2. Create temporary device instance to read actionSpace (always succeeds)
+     */
+    initTools(): Promise<void>;
+    /**
+     * Cleanup method - destroy agent and release resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get tool definitions
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /** Commands that exist only on the foreground CLI surface. */
+    getCliToolDefinitions(): ToolDefinition[];
+    /**
+     * Set agent for the tools manager
+     */
+    setAgent(agent: TAgent): void;
+    /**
+     * Set the default options injected into generated tool calls. Must be called
+     * before `initTools()` because the values are captured into the generated
+     * tool handlers. Merges with any previously set defaults.
+     */
+    setToolDefaults(toolDefaults: ToolDefaults): void;
+    /**
+     * Helper: Convert base64 screenshot to image content array
+     */
+    protected buildScreenshotContent(screenshot: string): {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }[];
+    /**
+     * Helper: Build a simple text result for tool responses
+     */
+    protected buildTextResult(text: string): {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    };
+    /**
+     * Create a disconnect handler for releasing platform resources
+     * @param platformName Human-readable platform name for the response message
+     * @returns Handler function that destroys the agent and returns appropriate response
+     */
+    protected createDisconnectHandler(platformName: string): () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+}

package/dist/types/agent-tools/chrome-path.d.ts

@@ -0,0 +1,2 @@
+export declare function getSystemChromePath(): string | undefined;
+export declare function resolveChromePath(): string;

package/dist/types/agent-tools/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/agent-tools/error-formatter.d.ts

@@ -0,0 +1,30 @@
+/** A compact, transport-safe representation of an unknown thrown value. */
+export interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string | number;
+    status?: string | number;
+    requestId?: string | number;
+}
+/** Apply the same string bound used by {@link serializeError}. */
+export declare function truncateSerializedErrorString(value: string): string;
+/**
+ * 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. This helper returns the bounded message from
+ * {@link serializeError}; message-less objects are summarized from the same
+ * diagnostic whitelist instead of serializing arbitrary payload fields.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/** Safely read a stack trace from an unknown thrown value when one exists. */
+export declare function getErrorStack(error: unknown): string | undefined;
+/**
+ * Extract a small, bounded diagnostic object suitable for JSON and test-runner
+ * transports. Only message, stack, and a few common diagnostic fields are
+ * retained. Arbitrary payloads are never visited, and nested errors are only
+ * inspected one level deep when the outer value has no message of its own.
+ */
+export declare function serializeError(error: unknown): SerializedError;

package/dist/types/agent-tools/index.d.ts

@@ -0,0 +1,9 @@
+export * from './base-tools';
+export * from './tool-defaults';
+export * from './agent-behavior-init-args';
+export * from './init-arg-utils';
+export * from './error-formatter';
+export * from './tool-generator';
+export * from './types';
+export * from './chrome-path';
+export * from './observation-record';

package/dist/types/agent-tools/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 tool schema whose keys are dotted `"<namespace>.<field>"`.
+ *
+ * We intentionally stay flat (rather than `{ namespace: z.object({...}) }`) so
+ * that CLI (`--android.device-id`) and `--help` output 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/agent-tools/observation-artifact.d.ts

@@ -0,0 +1,10 @@
+import type { BaseAgent, BaseUIObservation, UIObservationRecord } from './types';
+/** CLI-only bridge between an Agent runtime and observation artifacts. */
+export interface ObservationArtifactAdapter {
+    exportRecord(observation: BaseUIObservation): Promise<UIObservationRecord>;
+    loadRecord(record: UIObservationRecord): BaseUIObservation;
+}
+/** @internal Property key used by Core and the CLI artifact commands. */
+export declare const observationArtifactAdapterSymbol: unique symbol;
+/** Read the CLI artifact capability attached by the Core Agent. */
+export declare function resolveObservationArtifactAdapter(agent: BaseAgent): ObservationArtifactAdapter | undefined;

package/dist/types/agent-tools/observation-record.d.ts

@@ -0,0 +1,38 @@
+import type { UIObservationFrame, UIObservationRecord } from './types';
+export declare function defaultObservationRecordPath(): string;
+export declare function parseUIObservationRecord(input: unknown): UIObservationRecord;
+/** Return a detached record so callers cannot mutate runtime-owned state. */
+export declare function cloneUIObservationRecord(record: UIObservationRecord): UIObservationRecord;
+export declare function readUIObservationRecord(filePath: string): UIObservationRecord;
+export interface UIObservationRecordMetadata {
+    startedAt: number;
+    endedAt: number;
+    shotSize: UIObservationRecord['shotSize'];
+    shrunkShotToLogicalRatio: number;
+}
+/**
+ * Incrementally persists observation frames and exports a runtime record whose
+ * paths resolve to those image files.
+ */
+export declare class UIObservationRecordWriter {
+    readonly outputPath: string;
+    readonly framesDirectory: string;
+    private readonly temporaryFramesDirectory;
+    private finalized;
+    private disposed;
+    private finalizedRecord;
+    constructor(filePath?: string);
+    persistFrame(dataUrl: string, capturedAt: number): UIObservationFrame;
+    /** Resolve a persisted frame before or after the writer is finalized. */
+    resolveFramePath(frame: UIObservationFrame): string;
+    /** Remove persisted images that are no longer referenced by the frame buffer. */
+    pruneFrames(frames: UIObservationFrame[]): void;
+    finalize(frames: UIObservationFrame[], metadata: UIObservationRecordMetadata): UIObservationRecord;
+    /** Delete writer-owned temporary or finalized frame files. */
+    dispose(): void;
+}
+/**
+ * Persist a resolved observation record as a portable JSON manifest plus an
+ * adjacent image directory. The input record remains usable after writing.
+ */
+export declare function writeUIObservationRecord(record: UIObservationRecord, filePath?: string): string;

package/dist/types/agent-tools/tool-defaults.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Unified, declarative mechanism for "force a default option on every tool
+ * call" behaviors exposed by device and Agent Skill CLIs.
+ *
+ * Adding a new behavior flag (e.g. `--deep-search`) is a one-line change to
+ * {@link TOOL_BEHAVIOR_FLAGS}: declare which default-option "bag" it fills.
+ * The tool generator, tools managers and CLI parsing are all generic
+ * over {@link ToolDefaults} and never need to learn about individual flags.
+ *
+ * See https://github.com/web-infra-dev/midscene/issues/2446.
+ */
+/**
+ * Default options injected into generated tool calls. Each field is an
+ * injection point; an explicit per-call value always wins over these defaults.
+ */
+export interface ToolDefaults {
+    /**
+     * Merged into every locate field of action tools (`Tap`, `Input`, ...).
+     * e.g. `{ deepLocate: true }`.
+     */
+    locate?: Record<string, unknown>;
+    /**
+     * Merged into the `aiAction` options used by the `act` tool.
+     * e.g. `{ deepLocate: true, deepThink: true }`.
+     */
+    act?: Record<string, unknown>;
+}
+export interface ToolBehaviorFlag {
+    /** Kebab-case CLI flag name, e.g. `deep-locate` (exposed as `--deep-locate`). */
+    cli: string;
+    /** One-line description for help output. */
+    description: string;
+    /** Default-option bags this flag turns on when present. */
+    defaults: ToolDefaults;
+}
+/**
+ * The single source of truth for behavior flags. Add a row to support a new
+ * `--flag`; nothing else in the pipeline needs to change.
+ */
+export declare const TOOL_BEHAVIOR_FLAGS: readonly ToolBehaviorFlag[];
+/** Merge two {@link ToolDefaults}, with `b` taking precedence over `a`. */
+export declare function mergeToolDefaults(a: ToolDefaults, b: ToolDefaults): ToolDefaults;
+/**
+ * Resolve the active {@link ToolDefaults} from a predicate that says whether a
+ * given flag (by its `cli` name) is enabled.
+ */
+export declare function resolveToolDefaults(isEnabled: (cli: string) => boolean): ToolDefaults;
+/**
+ * Split argv into the resolved {@link ToolDefaults} and the remaining args.
+ *
+ * Behavior flags (e.g. `--deep-locate`) are global: they may appear anywhere
+ * in argv and are not tied to a specific sub-command. They are recognized by
+ * exact kebab-case match and removed so a strict per-command parser never sees them. Every other
+ * token is returned untouched and in order for that per-command parser.
+ *
+ * This is the single place that knows how a behavior flag looks on the command
+ * line; the device / Agent Skill CLI resolves defaults from
+ * {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
+ */
+export declare function stripBehaviorFlags(argv: readonly string[]): {
+    rawArgs: string[];
+    toolDefaults: ToolDefaults;
+};