@midscene/shared 1.0.1-beta-20251022061922.0 → 1.0.1-beta-20251024063839.0

package/src/env/types.ts

@@ -1,10 +1,10 @@
 // config keys
-export const MIDSCENE_OPENAI_INIT_CONFIG_JSON =
-  'MIDSCENE_OPENAI_INIT_CONFIG_JSON';
+export const MIDSCENE_MODEL_INIT_CONFIG_JSON =
+  'MIDSCENE_MODEL_INIT_CONFIG_JSON';
 export const MIDSCENE_MODEL_NAME = 'MIDSCENE_MODEL_NAME';
 export const MIDSCENE_LANGSMITH_DEBUG = 'MIDSCENE_LANGSMITH_DEBUG';
-export const MIDSCENE_DEBUG_AI_PROFILE = 'MIDSCENE_DEBUG_AI_PROFILE';
-export const MIDSCENE_DEBUG_AI_RESPONSE = 'MIDSCENE_DEBUG_AI_RESPONSE';
+export const MIDSCENE_DEBUG_MODEL_PROFILE = 'MIDSCENE_DEBUG_MODEL_PROFILE';
+export const MIDSCENE_DEBUG_MODEL_RESPONSE = 'MIDSCENE_DEBUG_MODEL_RESPONSE';
 export const MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG =
   'MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG';
 export const MIDSCENE_DEBUG_MODE = 'MIDSCENE_DEBUG_MODE';
@@ -15,9 +15,20 @@ export const MIDSCENE_MCP_ANDROID_MODE = 'MIDSCENE_MCP_ANDROID_MODE';
 export const DOCKER_CONTAINER = 'DOCKER_CONTAINER';
 export const MIDSCENE_FORCE_DEEP_THINK = 'MIDSCENE_FORCE_DEEP_THINK';
 
-export const MIDSCENE_OPENAI_SOCKS_PROXY = 'MIDSCENE_OPENAI_SOCKS_PROXY';
-export const MIDSCENE_OPENAI_HTTP_PROXY = 'MIDSCENE_OPENAI_HTTP_PROXY';
+export const MIDSCENE_MODEL_SOCKS_PROXY = 'MIDSCENE_MODEL_SOCKS_PROXY';
+export const MIDSCENE_MODEL_HTTP_PROXY = 'MIDSCENE_MODEL_HTTP_PROXY';
+
+// New primary names for public API
+export const MODEL_API_KEY = 'MODEL_API_KEY';
+export const MODEL_BASE_URL = 'MODEL_BASE_URL';
+
+/**
+ * @deprecated Use MODEL_API_KEY instead. This is kept for backward compatibility.
+ */
 export const OPENAI_API_KEY = 'OPENAI_API_KEY';
+/**
+ * @deprecated Use MODEL_BASE_URL instead. This is kept for backward compatibility.
+ */
 export const OPENAI_BASE_URL = 'OPENAI_BASE_URL';
 export const OPENAI_MAX_TOKENS = 'OPENAI_MAX_TOKENS';
 
@@ -50,48 +61,48 @@ export const MIDSCENE_CACHE_MAX_FILENAME_LENGTH =
 export const MIDSCENE_RUN_DIR = 'MIDSCENE_RUN_DIR';
 
 // default new
-export const MIDSCENE_OPENAI_BASE_URL = 'MIDSCENE_OPENAI_BASE_URL';
-export const MIDSCENE_OPENAI_API_KEY = 'MIDSCENE_OPENAI_API_KEY';
-export const MIDSCENE_VL_MODE = 'MIDSCENE_VL_MODE';
+export const MIDSCENE_MODEL_BASE_URL = 'MIDSCENE_MODEL_BASE_URL';
+export const MIDSCENE_MODEL_API_KEY = 'MIDSCENE_MODEL_API_KEY';
+export const MIDSCENE_LOCATOR_MODE = 'MIDSCENE_LOCATOR_MODE';
 
 // VQA
 export const MIDSCENE_VQA_MODEL_NAME = 'MIDSCENE_VQA_MODEL_NAME';
-export const MIDSCENE_VQA_OPENAI_SOCKS_PROXY =
-  'MIDSCENE_VQA_OPENAI_SOCKS_PROXY';
-export const MIDSCENE_VQA_OPENAI_HTTP_PROXY = 'MIDSCENE_VQA_OPENAI_HTTP_PROXY';
-export const MIDSCENE_VQA_OPENAI_BASE_URL = 'MIDSCENE_VQA_OPENAI_BASE_URL';
-export const MIDSCENE_VQA_OPENAI_API_KEY = 'MIDSCENE_VQA_OPENAI_API_KEY';
-export const MIDSCENE_VQA_OPENAI_INIT_CONFIG_JSON =
-  'MIDSCENE_VQA_OPENAI_INIT_CONFIG_JSON';
-export const MIDSCENE_VQA_VL_MODE = 'MIDSCENE_VQA_VL_MODE';
+export const MIDSCENE_VQA_MODEL_SOCKS_PROXY = 'MIDSCENE_VQA_MODEL_SOCKS_PROXY';
+export const MIDSCENE_VQA_MODEL_HTTP_PROXY = 'MIDSCENE_VQA_MODEL_HTTP_PROXY';
+export const MIDSCENE_VQA_MODEL_BASE_URL = 'MIDSCENE_VQA_MODEL_BASE_URL';
+export const MIDSCENE_VQA_MODEL_API_KEY = 'MIDSCENE_VQA_MODEL_API_KEY';
+export const MIDSCENE_VQA_MODEL_INIT_CONFIG_JSON =
+  'MIDSCENE_VQA_MODEL_INIT_CONFIG_JSON';
+export const MIDSCENE_VQA_LOCATOR_MODE = 'MIDSCENE_VQA_LOCATOR_MODE';
 
 // PLANNING
 export const MIDSCENE_PLANNING_MODEL_NAME = 'MIDSCENE_PLANNING_MODEL_NAME';
-export const MIDSCENE_PLANNING_OPENAI_SOCKS_PROXY =
-  'MIDSCENE_PLANNING_OPENAI_SOCKS_PROXY';
-export const MIDSCENE_PLANNING_OPENAI_HTTP_PROXY =
-  'MIDSCENE_PLANNING_OPENAI_HTTP_PROXY';
-export const MIDSCENE_PLANNING_OPENAI_BASE_URL =
-  'MIDSCENE_PLANNING_OPENAI_BASE_URL';
-export const MIDSCENE_PLANNING_OPENAI_API_KEY =
-  'MIDSCENE_PLANNING_OPENAI_API_KEY';
-export const MIDSCENE_PLANNING_OPENAI_INIT_CONFIG_JSON =
-  'MIDSCENE_PLANNING_OPENAI_INIT_CONFIG_JSON';
-export const MIDSCENE_PLANNING_VL_MODE = 'MIDSCENE_PLANNING_VL_MODE';
+export const MIDSCENE_PLANNING_MODEL_SOCKS_PROXY =
+  'MIDSCENE_PLANNING_MODEL_SOCKS_PROXY';
+export const MIDSCENE_PLANNING_MODEL_HTTP_PROXY =
+  'MIDSCENE_PLANNING_MODEL_HTTP_PROXY';
+export const MIDSCENE_PLANNING_MODEL_BASE_URL =
+  'MIDSCENE_PLANNING_MODEL_BASE_URL';
+export const MIDSCENE_PLANNING_MODEL_API_KEY =
+  'MIDSCENE_PLANNING_MODEL_API_KEY';
+export const MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON =
+  'MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON';
+export const MIDSCENE_PLANNING_LOCATOR_MODE = 'MIDSCENE_PLANNING_LOCATOR_MODE';
 
 // GROUNDING
 export const MIDSCENE_GROUNDING_MODEL_NAME = 'MIDSCENE_GROUNDING_MODEL_NAME';
-export const MIDSCENE_GROUNDING_OPENAI_SOCKS_PROXY =
-  'MIDSCENE_GROUNDING_OPENAI_SOCKS_PROXY';
-export const MIDSCENE_GROUNDING_OPENAI_HTTP_PROXY =
-  'MIDSCENE_GROUNDING_OPENAI_HTTP_PROXY';
-export const MIDSCENE_GROUNDING_OPENAI_BASE_URL =
-  'MIDSCENE_GROUNDING_OPENAI_BASE_URL';
-export const MIDSCENE_GROUNDING_OPENAI_API_KEY =
-  'MIDSCENE_GROUNDING_OPENAI_API_KEY';
-export const MIDSCENE_GROUNDING_OPENAI_INIT_CONFIG_JSON =
-  'MIDSCENE_GROUNDING_OPENAI_INIT_CONFIG_JSON';
-export const MIDSCENE_GROUNDING_VL_MODE = 'MIDSCENE_GROUNDING_VL_MODE';
+export const MIDSCENE_GROUNDING_MODEL_SOCKS_PROXY =
+  'MIDSCENE_GROUNDING_MODEL_SOCKS_PROXY';
+export const MIDSCENE_GROUNDING_MODEL_HTTP_PROXY =
+  'MIDSCENE_GROUNDING_MODEL_HTTP_PROXY';
+export const MIDSCENE_GROUNDING_MODEL_BASE_URL =
+  'MIDSCENE_GROUNDING_MODEL_BASE_URL';
+export const MIDSCENE_GROUNDING_MODEL_API_KEY =
+  'MIDSCENE_GROUNDING_MODEL_API_KEY';
+export const MIDSCENE_GROUNDING_MODEL_INIT_CONFIG_JSON =
+  'MIDSCENE_GROUNDING_MODEL_INIT_CONFIG_JSON';
+export const MIDSCENE_GROUNDING_LOCATOR_MODE =
+  'MIDSCENE_GROUNDING_LOCATOR_MODE';
 
 /**
  * env keys declared but unused
@@ -104,8 +115,8 @@ export const UNUSED_ENV_KEYS = [MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG];
  */
 export const BASIC_ENV_KEYS = [
   MIDSCENE_DEBUG_MODE,
-  MIDSCENE_DEBUG_AI_PROFILE,
-  MIDSCENE_DEBUG_AI_RESPONSE,
+  MIDSCENE_DEBUG_MODEL_PROFILE,
+  MIDSCENE_DEBUG_MODEL_RESPONSE,
   MIDSCENE_RUN_DIR,
 ] as const;
 
@@ -156,45 +167,47 @@ export const GLOBAL_ENV_KEYS = [
 export const MODEL_ENV_KEYS = [
   // model default
   MIDSCENE_MODEL_NAME,
-  MIDSCENE_OPENAI_INIT_CONFIG_JSON,
-  MIDSCENE_OPENAI_API_KEY,
-  MIDSCENE_OPENAI_BASE_URL,
-  MIDSCENE_OPENAI_SOCKS_PROXY,
-  MIDSCENE_OPENAI_HTTP_PROXY,
+  MIDSCENE_MODEL_INIT_CONFIG_JSON,
+  MIDSCENE_MODEL_API_KEY,
+  MIDSCENE_MODEL_BASE_URL,
+  MIDSCENE_MODEL_SOCKS_PROXY,
+  MIDSCENE_MODEL_HTTP_PROXY,
   MIDSCENE_USE_VLM_UI_TARS,
   MIDSCENE_USE_QWEN_VL,
   MIDSCENE_USE_QWEN3_VL,
   MIDSCENE_USE_DOUBAO_VISION,
   MIDSCENE_USE_GEMINI,
   MIDSCENE_USE_VL_MODEL,
-  MIDSCENE_VL_MODE,
+  MIDSCENE_LOCATOR_MODE,
   // model default legacy
   OPENAI_API_KEY,
   OPENAI_BASE_URL,
+  MODEL_API_KEY,
+  MODEL_BASE_URL,
   // VQA
   MIDSCENE_VQA_MODEL_NAME,
-  MIDSCENE_VQA_OPENAI_SOCKS_PROXY,
-  MIDSCENE_VQA_OPENAI_HTTP_PROXY,
-  MIDSCENE_VQA_OPENAI_BASE_URL,
-  MIDSCENE_VQA_OPENAI_API_KEY,
-  MIDSCENE_VQA_OPENAI_INIT_CONFIG_JSON,
-  MIDSCENE_VQA_VL_MODE,
+  MIDSCENE_VQA_MODEL_SOCKS_PROXY,
+  MIDSCENE_VQA_MODEL_HTTP_PROXY,
+  MIDSCENE_VQA_MODEL_BASE_URL,
+  MIDSCENE_VQA_MODEL_API_KEY,
+  MIDSCENE_VQA_MODEL_INIT_CONFIG_JSON,
+  MIDSCENE_VQA_LOCATOR_MODE,
   // PLANNING
   MIDSCENE_PLANNING_MODEL_NAME,
-  MIDSCENE_PLANNING_OPENAI_SOCKS_PROXY,
-  MIDSCENE_PLANNING_OPENAI_HTTP_PROXY,
-  MIDSCENE_PLANNING_OPENAI_BASE_URL,
-  MIDSCENE_PLANNING_OPENAI_API_KEY,
-  MIDSCENE_PLANNING_OPENAI_INIT_CONFIG_JSON,
-  MIDSCENE_PLANNING_VL_MODE,
+  MIDSCENE_PLANNING_MODEL_SOCKS_PROXY,
+  MIDSCENE_PLANNING_MODEL_HTTP_PROXY,
+  MIDSCENE_PLANNING_MODEL_BASE_URL,
+  MIDSCENE_PLANNING_MODEL_API_KEY,
+  MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
+  MIDSCENE_PLANNING_LOCATOR_MODE,
   // GROUNDING
   MIDSCENE_GROUNDING_MODEL_NAME,
-  MIDSCENE_GROUNDING_OPENAI_SOCKS_PROXY,
-  MIDSCENE_GROUNDING_OPENAI_HTTP_PROXY,
-  MIDSCENE_GROUNDING_OPENAI_BASE_URL,
-  MIDSCENE_GROUNDING_OPENAI_API_KEY,
-  MIDSCENE_GROUNDING_OPENAI_INIT_CONFIG_JSON,
-  MIDSCENE_GROUNDING_VL_MODE,
+  MIDSCENE_GROUNDING_MODEL_SOCKS_PROXY,
+  MIDSCENE_GROUNDING_MODEL_HTTP_PROXY,
+  MIDSCENE_GROUNDING_MODEL_BASE_URL,
+  MIDSCENE_GROUNDING_MODEL_API_KEY,
+  MIDSCENE_GROUNDING_MODEL_INIT_CONFIG_JSON,
+  MIDSCENE_GROUNDING_LOCATOR_MODE,
 ] as const;
 
 export const ALL_ENV_KEYS = [
@@ -227,14 +240,14 @@ export interface IModelConfigForVQA {
   // model name
   [MIDSCENE_VQA_MODEL_NAME]: string;
   // proxy
-  [MIDSCENE_VQA_OPENAI_SOCKS_PROXY]?: string;
-  [MIDSCENE_VQA_OPENAI_HTTP_PROXY]?: string;
+  [MIDSCENE_VQA_MODEL_SOCKS_PROXY]?: string;
+  [MIDSCENE_VQA_MODEL_HTTP_PROXY]?: string;
   // OpenAI
-  [MIDSCENE_VQA_OPENAI_BASE_URL]?: string;
-  [MIDSCENE_VQA_OPENAI_API_KEY]?: string;
-  [MIDSCENE_VQA_OPENAI_INIT_CONFIG_JSON]?: string;
+  [MIDSCENE_VQA_MODEL_BASE_URL]?: string;
+  [MIDSCENE_VQA_MODEL_API_KEY]?: string;
+  [MIDSCENE_VQA_MODEL_INIT_CONFIG_JSON]?: string;
   // extra
-  [MIDSCENE_VQA_VL_MODE]?: TVlModeValues;
+  [MIDSCENE_VQA_LOCATOR_MODE]?: TVlModeValues;
 }
 
 /**
@@ -243,7 +256,7 @@ export interface IModelConfigForVQA {
  * IMPORTANT: Planning MUST use a vision language model (VL mode).
  * DOM-based planning is not supported.
  *
- * Required: MIDSCENE_PLANNING_VL_MODE must be set to one of:
+ * Required: MIDSCENE_PLANNING_LOCATOR_MODE must be set to one of:
  *   - 'qwen-vl'
  *   - 'qwen3-vl'
  *   - 'gemini'
@@ -256,56 +269,56 @@ export interface IModelConfigForPlanning {
   // model name
   [MIDSCENE_PLANNING_MODEL_NAME]: string;
   // proxy
-  [MIDSCENE_PLANNING_OPENAI_SOCKS_PROXY]?: string;
-  [MIDSCENE_PLANNING_OPENAI_HTTP_PROXY]?: string;
+  [MIDSCENE_PLANNING_MODEL_SOCKS_PROXY]?: string;
+  [MIDSCENE_PLANNING_MODEL_HTTP_PROXY]?: string;
   // OpenAI
-  [MIDSCENE_PLANNING_OPENAI_BASE_URL]?: string;
-  [MIDSCENE_PLANNING_OPENAI_API_KEY]?: string;
-  [MIDSCENE_PLANNING_OPENAI_INIT_CONFIG_JSON]?: string;
+  [MIDSCENE_PLANNING_MODEL_BASE_URL]?: string;
+  [MIDSCENE_PLANNING_MODEL_API_KEY]?: string;
+  [MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON]?: string;
   // extra
-  [MIDSCENE_PLANNING_VL_MODE]?: TVlModeValues;
+  [MIDSCENE_PLANNING_LOCATOR_MODE]?: TVlModeValues;
 }
 
 export interface IModeConfigForGrounding {
   // model name
   [MIDSCENE_GROUNDING_MODEL_NAME]: string;
   // proxy
-  [MIDSCENE_GROUNDING_OPENAI_SOCKS_PROXY]?: string;
-  [MIDSCENE_GROUNDING_OPENAI_HTTP_PROXY]?: string;
+  [MIDSCENE_GROUNDING_MODEL_SOCKS_PROXY]?: string;
+  [MIDSCENE_GROUNDING_MODEL_HTTP_PROXY]?: string;
   // OpenAI
-  [MIDSCENE_GROUNDING_OPENAI_BASE_URL]?: string;
-  [MIDSCENE_GROUNDING_OPENAI_API_KEY]?: string;
-  [MIDSCENE_GROUNDING_OPENAI_INIT_CONFIG_JSON]?: string;
+  [MIDSCENE_GROUNDING_MODEL_BASE_URL]?: string;
+  [MIDSCENE_GROUNDING_MODEL_API_KEY]?: string;
+  [MIDSCENE_GROUNDING_MODEL_INIT_CONFIG_JSON]?: string;
   // extra
-  [MIDSCENE_GROUNDING_VL_MODE]?: TVlModeValues;
+  [MIDSCENE_GROUNDING_LOCATOR_MODE]?: TVlModeValues;
 }
 
 export interface IModelConfigForDefault {
   // model name
   [MIDSCENE_MODEL_NAME]: string;
   // proxy
-  [MIDSCENE_OPENAI_SOCKS_PROXY]?: string;
-  [MIDSCENE_OPENAI_HTTP_PROXY]?: string;
+  [MIDSCENE_MODEL_SOCKS_PROXY]?: string;
+  [MIDSCENE_MODEL_HTTP_PROXY]?: string;
   // OpenAI
-  [MIDSCENE_OPENAI_BASE_URL]?: string;
-  [MIDSCENE_OPENAI_API_KEY]?: string;
-  [MIDSCENE_OPENAI_INIT_CONFIG_JSON]?: string;
+  [MIDSCENE_MODEL_BASE_URL]?: string;
+  [MIDSCENE_MODEL_API_KEY]?: string;
+  [MIDSCENE_MODEL_INIT_CONFIG_JSON]?: string;
   // extra
-  [MIDSCENE_VL_MODE]?: TVlModeValues;
+  [MIDSCENE_LOCATOR_MODE]?: TVlModeValues;
 }
 
 export interface IModelConfigForDefaultLegacy {
   // model name
   [MIDSCENE_MODEL_NAME]: string;
   // proxy
-  [MIDSCENE_OPENAI_SOCKS_PROXY]?: string;
-  [MIDSCENE_OPENAI_HTTP_PROXY]?: string;
+  [MIDSCENE_MODEL_SOCKS_PROXY]?: string;
+  [MIDSCENE_MODEL_HTTP_PROXY]?: string;
   // OpenAI
   [OPENAI_BASE_URL]?: string;
   [OPENAI_API_KEY]?: string;
-  [MIDSCENE_OPENAI_INIT_CONFIG_JSON]?: string;
+  [MIDSCENE_MODEL_INIT_CONFIG_JSON]?: string;
   // extra
-  [MIDSCENE_VL_MODE]?: TVlModeValues;
+  [MIDSCENE_LOCATOR_MODE]?: TVlModeValues;
 }
 
 /**
@@ -316,7 +329,11 @@ export interface IModelConfigForDefaultLegacy {
  */
 export type TIntent = 'VQA' | 'planning' | 'grounding' | 'default';
 
-export type TModelConfigFn = (options: {
+/**
+ * Internal type with intent parameter for ModelConfigManager
+ * @internal
+ */
+export type TModelConfigFnInternal = (options: {
   intent: TIntent;
 }) =>
   | IModelConfigForVQA
@@ -324,6 +341,16 @@ export type TModelConfigFn = (options: {
   | IModeConfigForGrounding
   | IModelConfigForDefault;
 
+/**
+ * User-facing model config function type
+ * Users return config objects without needing to know about intent parameter
+ */
+export type TModelConfigFn = () =>
+  | IModelConfigForVQA
+  | IModelConfigForPlanning
+  | IModeConfigForGrounding
+  | IModelConfigForDefault;
+
 export enum UITarsModelVersion {
   V1_0 = '1.0',
   V1_5 = '1.5',