@midscene/shared 1.12.4-beta-20260904041024.0 → 1.12.4

package/dist/es/agent-tools/agent-behavior-init-args.mjs

@@ -1,13 +1,19 @@
 import { z } from "zod";
+import { AGENT_AI_CONTEXT_KEYS, isAgentAIContextKey } from "./agent-context.mjs";
 const agentBehaviorInitArgShape = {
-    aiActContext: z.string().optional().describe('Background knowledge passed to aiAct. Default: no extra context.'),
+    aiContexts: z.record(z["enum"](AGENT_AI_CONTEXT_KEYS), z.string()).optional().describe('Additional AI guidance such as business facts, rules, constraints, or output requirements. aiContexts.default is used only when neither the call nor its API key provides a context. Values override rather than automatically merge.'),
+    aiActContext: z.string().optional().describe('Deprecated compatibility alias for aiContexts.aiAct. aiContexts.aiAct takes precedence when both are provided.'),
     replanningCycleLimit: z.number().int().nonnegative().optional().describe('Maximum number of replanning cycles for aiAct. Default: model adapter default.'),
     waitAfterAction: z.number().nonnegative().optional().describe('Wait time in milliseconds after each action execution. Default: 300ms.'),
     screenshotShrinkFactor: z.number().min(1).optional().describe('Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.')
 };
 function extractAgentBehaviorInitArgs(extracted) {
     if (!extracted) return;
+    const aiContexts = Object.fromEntries(Object.entries(extracted.aiContexts ?? {}).filter(([key, value])=>isAgentAIContextKey(key) && 'string' == typeof value));
     const agentOptions = {
+        ...Object.keys(aiContexts).length > 0 ? {
+            aiContexts
+        } : {},
         ...'string' == typeof extracted.aiActContext ? {
             aiActContext: extracted.aiActContext
         } : {},

package/dist/es/agent-tools/agent-context.mjs

@@ -0,0 +1,27 @@
+const AI_API_NAMES = [
+    'aiAct',
+    'aiTap',
+    'aiRightClick',
+    'aiDoubleClick',
+    'aiHover',
+    'aiInput',
+    'aiKeyboardPress',
+    'aiScroll',
+    'aiPinch',
+    'aiLongPress',
+    'aiClearInput',
+    'aiLocate',
+    'aiQuery',
+    'aiBoolean',
+    'aiNumber',
+    'aiString',
+    'aiAsk',
+    'aiAssert',
+    'aiWaitFor'
+];
+const AGENT_AI_CONTEXT_KEYS = [
+    'default',
+    ...AI_API_NAMES
+];
+const isAgentAIContextKey = (value)=>'string' == typeof value && AGENT_AI_CONTEXT_KEYS.includes(value);
+export { AGENT_AI_CONTEXT_KEYS, AI_API_NAMES, isAgentAIContextKey };

package/dist/es/agent-tools/index.mjs

@@ -1,6 +1,7 @@
 export * from "./base-tools.mjs";
 export * from "./tool-defaults.mjs";
 export * from "./agent-behavior-init-args.mjs";
+export * from "./agent-context.mjs";
 export * from "./init-arg-utils.mjs";
 export * from "./error-formatter.mjs";
 export * from "./tool-generator.mjs";

package/dist/es/env/parse-model-config.mjs

@@ -5,7 +5,7 @@ import { assert } from "../utils.mjs";
 import { maskConfig, parseJson } from "./helper.mjs";
 import { initDebugConfig } from "./init-debug.mjs";
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.12.4-beta-20260904041024.0";
+const getCurrentVersion = ()=>"1.12.4";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: INSIGHT_MODEL_CONFIG_KEYS,

package/dist/lib/agent-tools/agent-behavior-init-args.js

@@ -30,15 +30,21 @@ __webpack_require__.d(__webpack_exports__, {
     shouldRebuildAgentForInitArgs: ()=>shouldRebuildAgentForInitArgs
 });
 const external_zod_namespaceObject = require("zod");
+const external_agent_context_js_namespaceObject = require("./agent-context.js");
 const agentBehaviorInitArgShape = {
-    aiActContext: external_zod_namespaceObject.z.string().optional().describe('Background knowledge passed to aiAct. Default: no extra context.'),
+    aiContexts: external_zod_namespaceObject.z.record(external_zod_namespaceObject.z["enum"](external_agent_context_js_namespaceObject.AGENT_AI_CONTEXT_KEYS), external_zod_namespaceObject.z.string()).optional().describe('Additional AI guidance such as business facts, rules, constraints, or output requirements. aiContexts.default is used only when neither the call nor its API key provides a context. Values override rather than automatically merge.'),
+    aiActContext: external_zod_namespaceObject.z.string().optional().describe('Deprecated compatibility alias for aiContexts.aiAct. aiContexts.aiAct takes precedence when both are provided.'),
     replanningCycleLimit: external_zod_namespaceObject.z.number().int().nonnegative().optional().describe('Maximum number of replanning cycles for aiAct. Default: model adapter default.'),
     waitAfterAction: external_zod_namespaceObject.z.number().nonnegative().optional().describe('Wait time in milliseconds after each action execution. Default: 300ms.'),
     screenshotShrinkFactor: external_zod_namespaceObject.z.number().min(1).optional().describe('Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.')
 };
 function extractAgentBehaviorInitArgs(extracted) {
     if (!extracted) return;
+    const aiContexts = Object.fromEntries(Object.entries(extracted.aiContexts ?? {}).filter(([key, value])=>(0, external_agent_context_js_namespaceObject.isAgentAIContextKey)(key) && 'string' == typeof value));
     const agentOptions = {
+        ...Object.keys(aiContexts).length > 0 ? {
+            aiContexts
+        } : {},
         ...'string' == typeof extracted.aiActContext ? {
             aiActContext: extracted.aiActContext
         } : {},

package/dist/lib/agent-tools/agent-context.js

@@ -0,0 +1,67 @@
+"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__, {
+    AGENT_AI_CONTEXT_KEYS: ()=>AGENT_AI_CONTEXT_KEYS,
+    AI_API_NAMES: ()=>AI_API_NAMES,
+    isAgentAIContextKey: ()=>isAgentAIContextKey
+});
+const AI_API_NAMES = [
+    'aiAct',
+    'aiTap',
+    'aiRightClick',
+    'aiDoubleClick',
+    'aiHover',
+    'aiInput',
+    'aiKeyboardPress',
+    'aiScroll',
+    'aiPinch',
+    'aiLongPress',
+    'aiClearInput',
+    'aiLocate',
+    'aiQuery',
+    'aiBoolean',
+    'aiNumber',
+    'aiString',
+    'aiAsk',
+    'aiAssert',
+    'aiWaitFor'
+];
+const AGENT_AI_CONTEXT_KEYS = [
+    'default',
+    ...AI_API_NAMES
+];
+const isAgentAIContextKey = (value)=>'string' == typeof value && AGENT_AI_CONTEXT_KEYS.includes(value);
+exports.AGENT_AI_CONTEXT_KEYS = __webpack_exports__.AGENT_AI_CONTEXT_KEYS;
+exports.AI_API_NAMES = __webpack_exports__.AI_API_NAMES;
+exports.isAgentAIContextKey = __webpack_exports__.isAgentAIContextKey;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "AGENT_AI_CONTEXT_KEYS",
+    "AI_API_NAMES",
+    "isAgentAIContextKey"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/lib/agent-tools/index.js

@@ -3,6 +3,9 @@ var __webpack_modules__ = {
     "./agent-behavior-init-args" (module) {
         module.exports = require("./agent-behavior-init-args.js");
     },
+    "./agent-context" (module) {
+        module.exports = require("./agent-context.js");
+    },
     "./base-tools" (module) {
         module.exports = require("./base-tools.js");
     },
@@ -83,29 +86,33 @@ var __webpack_exports__ = {};
     var __rspack_reexport = {};
     for(const __rspack_import_key in _agent_behavior_init_args__rspack_import_2)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_agent_behavior_init_args__rspack_import_2[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _init_arg_utils__rspack_import_3 = __webpack_require__("./init-arg-utils");
+    var _agent_context__rspack_import_3 = __webpack_require__("./agent-context");
+    var __rspack_reexport = {};
+    for(const __rspack_import_key in _agent_context__rspack_import_3)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_agent_context__rspack_import_3[__rspack_import_key];
+    __webpack_require__.d(__webpack_exports__, __rspack_reexport);
+    var _init_arg_utils__rspack_import_4 = __webpack_require__("./init-arg-utils");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _init_arg_utils__rspack_import_3)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_init_arg_utils__rspack_import_3[__rspack_import_key];
+    for(const __rspack_import_key in _init_arg_utils__rspack_import_4)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_init_arg_utils__rspack_import_4[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _error_formatter__rspack_import_4 = __webpack_require__("./error-formatter");
+    var _error_formatter__rspack_import_5 = __webpack_require__("./error-formatter");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _error_formatter__rspack_import_4)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_error_formatter__rspack_import_4[__rspack_import_key];
+    for(const __rspack_import_key in _error_formatter__rspack_import_5)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_error_formatter__rspack_import_5[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _tool_generator__rspack_import_5 = __webpack_require__("./tool-generator");
+    var _tool_generator__rspack_import_6 = __webpack_require__("./tool-generator");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _tool_generator__rspack_import_5)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_tool_generator__rspack_import_5[__rspack_import_key];
+    for(const __rspack_import_key in _tool_generator__rspack_import_6)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_tool_generator__rspack_import_6[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _types__rspack_import_6 = __webpack_require__("./types");
+    var _types__rspack_import_7 = __webpack_require__("./types");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _types__rspack_import_6)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_types__rspack_import_6[__rspack_import_key];
+    for(const __rspack_import_key in _types__rspack_import_7)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_types__rspack_import_7[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _chrome_path__rspack_import_7 = __webpack_require__("./chrome-path");
+    var _chrome_path__rspack_import_8 = __webpack_require__("./chrome-path");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _chrome_path__rspack_import_7)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_chrome_path__rspack_import_7[__rspack_import_key];
+    for(const __rspack_import_key in _chrome_path__rspack_import_8)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_chrome_path__rspack_import_8[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _observation_record__rspack_import_8 = __webpack_require__("./observation-record");
+    var _observation_record__rspack_import_9 = __webpack_require__("./observation-record");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _observation_record__rspack_import_8)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_observation_record__rspack_import_8[__rspack_import_key];
+    for(const __rspack_import_key in _observation_record__rspack_import_9)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_observation_record__rspack_import_9[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
 })();
 for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];

package/dist/lib/env/parse-model-config.js

@@ -37,7 +37,7 @@ const external_utils_js_namespaceObject = require("../utils.js");
 const external_helper_js_namespaceObject = require("./helper.js");
 const external_init_debug_js_namespaceObject = require("./init-debug.js");
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.12.4-beta-20260904041024.0";
+const getCurrentVersion = ()=>"1.12.4";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${external_types_js_namespaceObject.MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: external_constants_js_namespaceObject.INSIGHT_MODEL_CONFIG_KEYS,

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

@@ -1,12 +1,29 @@
 import { z } from 'zod';
+import { type AgentAIContexts } from './agent-context';
 export interface AgentBehaviorInitArgs {
+    /**
+     * Agent-level AI guidance. `default` is used only when neither the current
+     * call nor its API key provides a context. Values override rather than
+     * automatically merge.
+     */
+    aiContexts?: AgentAIContexts;
+    /**
+     * Compatibility alias for `aiContexts.aiAct`; that field wins when both
+     * exist.
+     * @deprecated Use `aiContexts.aiAct` instead.
+     */
     aiActContext?: string;
+    /**
+     * Older compatibility alias for `aiContexts.aiAct`.
+     * @deprecated Use `aiContexts.aiAct` instead.
+     */
     aiActionContext?: string;
     replanningCycleLimit?: number;
     waitAfterAction?: number;
     screenshotShrinkFactor?: number;
 }
 export declare const agentBehaviorInitArgShape: {
+    aiContexts: z.ZodOptional<z.ZodRecord<z.ZodEnum<["default", "aiAct", "aiTap", "aiRightClick", "aiDoubleClick", "aiHover", "aiInput", "aiKeyboardPress", "aiScroll", "aiPinch", "aiLongPress", "aiClearInput", "aiLocate", "aiQuery", "aiBoolean", "aiNumber", "aiString", "aiAsk", "aiAssert", "aiWaitFor"]>, z.ZodString>>;
     aiActContext: z.ZodOptional<z.ZodString>;
     replanningCycleLimit: z.ZodOptional<z.ZodNumber>;
     waitAfterAction: z.ZodOptional<z.ZodNumber>;

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

@@ -0,0 +1,18 @@
+export declare const AI_API_NAMES: readonly ["aiAct", "aiTap", "aiRightClick", "aiDoubleClick", "aiHover", "aiInput", "aiKeyboardPress", "aiScroll", "aiPinch", "aiLongPress", "aiClearInput", "aiLocate", "aiQuery", "aiBoolean", "aiNumber", "aiString", "aiAsk", "aiAssert", "aiWaitFor"];
+export type AiApiName = (typeof AI_API_NAMES)[number];
+export declare const AGENT_AI_CONTEXT_KEYS: readonly ["default", "aiAct", "aiTap", "aiRightClick", "aiDoubleClick", "aiHover", "aiInput", "aiKeyboardPress", "aiScroll", "aiPinch", "aiLongPress", "aiClearInput", "aiLocate", "aiQuery", "aiBoolean", "aiNumber", "aiString", "aiAsk", "aiAssert", "aiWaitFor"];
+export type AgentAIContextKey = (typeof AGENT_AI_CONTEXT_KEYS)[number];
+/**
+ * Additional AI guidance configured at Agent level. Values may contain
+ * business facts, decision or interaction rules, constraints, and output
+ * requirements. An API-specific value overrides `default`; values are not
+ * automatically merged.
+ */
+export type AgentAIContexts = {
+    /**
+     * Shared fallback for every AI-powered API. It is used only when neither
+     * the current call nor the matching API key provides a context.
+     */
+    default?: string;
+} & Partial<Record<AiApiName, string | undefined>>;
+export declare const isAgentAIContextKey: (value: unknown) => value is AgentAIContextKey;

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

@@ -1,6 +1,7 @@
 export * from './base-tools';
 export * from './tool-defaults';
 export * from './agent-behavior-init-args';
+export * from './agent-context';
 export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';

package/package.json

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

package/src/agent-tools/agent-behavior-init-args.ts

@@ -1,7 +1,27 @@
 import { z } from 'zod';
+import {
+  AGENT_AI_CONTEXT_KEYS,
+  type AgentAIContexts,
+  isAgentAIContextKey,
+} from './agent-context';
 
 export interface AgentBehaviorInitArgs {
+  /**
+   * Agent-level AI guidance. `default` is used only when neither the current
+   * call nor its API key provides a context. Values override rather than
+   * automatically merge.
+   */
+  aiContexts?: AgentAIContexts;
+  /**
+   * Compatibility alias for `aiContexts.aiAct`; that field wins when both
+   * exist.
+   * @deprecated Use `aiContexts.aiAct` instead.
+   */
   aiActContext?: string;
+  /**
+   * Older compatibility alias for `aiContexts.aiAct`.
+   * @deprecated Use `aiContexts.aiAct` instead.
+   */
   aiActionContext?: string;
   replanningCycleLimit?: number;
   waitAfterAction?: number;
@@ -14,11 +34,17 @@ type ExposedAgentBehaviorInitArgKey = Exclude<
 >;
 
 export const agentBehaviorInitArgShape = {
+  aiContexts: z
+    .record(z.enum(AGENT_AI_CONTEXT_KEYS), z.string())
+    .optional()
+    .describe(
+      'Additional AI guidance such as business facts, rules, constraints, or output requirements. aiContexts.default is used only when neither the call nor its API key provides a context. Values override rather than automatically merge.',
+    ),
   aiActContext: z
     .string()
     .optional()
     .describe(
-      'Background knowledge passed to aiAct. Default: no extra context.',
+      'Deprecated compatibility alias for aiContexts.aiAct. aiContexts.aiAct takes precedence when both are provided.',
     ),
   replanningCycleLimit: z
     .number()
@@ -51,7 +77,14 @@ export function extractAgentBehaviorInitArgs(
     return undefined;
   }
 
+  const aiContexts = Object.fromEntries(
+    Object.entries(extracted.aiContexts ?? {}).filter(
+      ([key, value]) => isAgentAIContextKey(key) && typeof value === 'string',
+    ),
+  ) as AgentAIContexts;
+
   const agentOptions: AgentBehaviorInitArgs = {
+    ...(Object.keys(aiContexts).length > 0 ? { aiContexts } : {}),
     ...(typeof extracted.aiActContext === 'string'
       ? { aiActContext: extracted.aiActContext }
       : {}),

package/src/agent-tools/agent-context.ts

@@ -0,0 +1,47 @@
+export const AI_API_NAMES = [
+  'aiAct',
+  'aiTap',
+  'aiRightClick',
+  'aiDoubleClick',
+  'aiHover',
+  'aiInput',
+  'aiKeyboardPress',
+  'aiScroll',
+  'aiPinch',
+  'aiLongPress',
+  'aiClearInput',
+  'aiLocate',
+  'aiQuery',
+  'aiBoolean',
+  'aiNumber',
+  'aiString',
+  'aiAsk',
+  'aiAssert',
+  'aiWaitFor',
+] as const;
+
+export type AiApiName = (typeof AI_API_NAMES)[number];
+
+export const AGENT_AI_CONTEXT_KEYS = ['default', ...AI_API_NAMES] as const;
+
+export type AgentAIContextKey = (typeof AGENT_AI_CONTEXT_KEYS)[number];
+
+/**
+ * Additional AI guidance configured at Agent level. Values may contain
+ * business facts, decision or interaction rules, constraints, and output
+ * requirements. An API-specific value overrides `default`; values are not
+ * automatically merged.
+ */
+export type AgentAIContexts = {
+  /**
+   * Shared fallback for every AI-powered API. It is used only when neither
+   * the current call nor the matching API key provides a context.
+   */
+  default?: string;
+} & Partial<Record<AiApiName, string | undefined>>;
+
+export const isAgentAIContextKey = (
+  value: unknown,
+): value is AgentAIContextKey =>
+  typeof value === 'string' &&
+  (AGENT_AI_CONTEXT_KEYS as readonly string[]).includes(value);

package/src/agent-tools/index.ts

@@ -1,6 +1,7 @@
 export * from './base-tools';
 export * from './tool-defaults';
 export * from './agent-behavior-init-args';
+export * from './agent-context';
 export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';