@reconcrap/boss-recommend-mcp 2.0.29 → 2.0.31

package/README.md

@@ -227,10 +227,35 @@ config/screening-config.example.json
 - `apiKey`
 - `model`
 
+也可以用 `llmModels` 配置多个 OpenAI-compatible 模型。运行时会先调用第一个模型；当该模型请求失败、超时、返回非 JSON、或没有返回 `{"passed": true/false}` 决策时，会自动切到下一个模型。未配置 `llmModels` 或数组为空时，继续使用上面的单模型字段，旧配置无需迁移。
+
+```json
+{
+  "llmModels": [
+    {
+      "name": "primary",
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "sk-primary",
+      "model": "gpt-4.1-mini"
+    },
+    {
+      "name": "backup",
+      "baseUrl": "https://api.openai.com/v1",
+      "apiKey": "sk-backup",
+      "model": "gpt-4.1-nano"
+    }
+  ],
+  "greetingMessage": "Hi同学，能麻烦发下简历吗？",
+  "llmThinkingLevel": "low",
+  "llmMaxRetries": 1
+}
+```
+
 可选字段：
 
 - `openaiOrganization`
 - `openaiProject`
+- `greetingMessage`：chat 求简历流程发送的招呼语。兼容 `greetingText` / `greeting_text`；本次 run 显式传入的 `greeting_text` 优先级最高。
 - `debugPort`：未显式传 `port` 时，recommend / search / chat CDP-only MCP run 和健康检查默认连接这个 Chrome 调试端口。
 - `outputDir`：recommend / search / chat 完成后的最终 CSV 与 report JSON 会写入这里；run state / checkpoint 仍保留在各自状态目录，方便 pause/resume/cancel。
 - `llmThinkingLevel`：默认 `low`。可设为 `off/minimal/low/medium/high/auto/current`，用于控制 OpenAI-compatible LLM 的 thinking/reasoning 强度。
@@ -243,7 +268,7 @@ npm 包安装后可直接使用可执行命令 `boss-recommend-mcp`。以下示
 ```bash
 node src/cli.js install --agent trae-cn
 node src/cli.js init-config
-node src/cli.js config set --base-url https://api.openai.com/v1 --api-key <your-key> --model gpt-4o-mini --thinking-level off
+node src/cli.js config set --base-url https://api.openai.com/v1 --api-key <your-key> --model gpt-4o-mini --thinking-level off --greeting-message "您好，方便发下简历吗？"
 node src/cli.js set-port --port 9222
 node src/cli.js doctor --agent trae-cn
 node src/cli.js launch-chrome --port 9222
@@ -283,7 +308,7 @@ node src/cli.js chat prepare-run --slow-live --port 9222
 - `profile` 可选，默认 `default`
 - `job` 与 `port` 继承 recommend run 已选岗位和调试端口
 - `baseUrl` / `apiKey` / `model` 不再单独传入，固定复用 recommend 的 `screening-config.json`
-- `greeting_text` 默认优先级：本次显式值 > profile 历史值 > 内置默认招呼语（`Hi同学，能麻烦发下简历吗？`）
+- `greeting_text` 默认优先级：本次显式值 > `screening-config.json.greetingMessage` > 内置默认招呼语（`Hi同学，能麻烦发下简历吗？`）
 - 若缺少 `follow_up.chat` 必填项，pipeline 会返回 `NEED_INPUT`
 - 如需聊天页筛选，请调用 `prepare_boss_chat_run` 获取岗位列表，再调用 `start_boss_chat_run`。
 - `boss-chat` 状态统一写入 `~/.boss-recommend-mcp/boss-chat`（或 `BOSS_CHAT_HOME` 指定目录），不再依赖工作区 `cwd`
@@ -313,7 +338,7 @@ chat-only 交互建议：
 
 - 先调用一次 `prepare_boss_chat_run`（可不带参数），服务会先导航到 `https://www.zhipin.com/web/chat/index` 并返回 `NEED_INPUT`，其中包含岗位 `job_options` 与待补字段。
 - 然后基于 `job_options` 让用户选择 `job`，并补齐 `start_from`、`target_count`、`criteria` 后调用 `start_boss_chat_run` 启动任务。
-- `greeting_text` 可选；未传时会自动沿用 profile 上次输入，若无历史值则使用默认招呼语（`Hi同学，能麻烦发下简历吗？`）。
+- `greeting_text` 可选；未传时使用 `screening-config.json.greetingMessage`，若未配置则使用默认招呼语（`Hi同学，能麻烦发下简历吗？`）。
 - `target_count` 支持正整数、`all`、`-1`；若用户给出 `全部候选人` / `所有候选人`，会自动按不限（扫到底）处理。
 
 Trae-CN / 长对话防循环建议：

package/config/screening-config.example.json

@@ -1,7 +1,9 @@
 {
-  "baseUrl": "https://api.openai.com/v1",
-  "apiKey": "replace-with-openai-api-key",
+  "baseUrl": "https://api.openai.com/v1",
+  "apiKey": "replace-with-openai-api-key",
   "model": "gpt-4.1-mini",
+  "llmModels": [],
+  "greetingMessage": "Hi同学，能麻烦发下简历吗？",
   "llmThinkingLevel": "low",
   "llmTimeoutMs": 60000,
   "llmMaxTokens": 512,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",

package/src/chat-mcp.js

@@ -874,12 +874,14 @@ async function readChatJobOptionsFromSession(session) {
 
 function normalizeChatStartInput(args = {}, configResolution = null) {
   const target = normalizeTargetCountInput(getBossChatTargetCountValue(args));
+  const explicitGreetingText = normalizeText(args.greeting_text || args.greetingText || args.greeting);
+  const configuredGreetingText = normalizeText(configResolution?.config?.greetingMessage || configResolution?.config?.greetingText);
   return {
     profile: normalizeText(args.profile) || "default",
     job: normalizeText(args.job),
     startFrom: normalizeText(args.start_from).toLowerCase(),
     criteria: normalizeText(args.criteria),
-    greetingText: normalizeText(args.greeting_text || args.greetingText || args.greeting),
+    greetingText: explicitGreetingText || configuredGreetingText,
     target,
     targetCount: target.targetCount,
     publicTargetCount: target.publicValue,

package/src/chat-runtime-config.js

@@ -243,6 +243,55 @@ function normalizeLlmThinkingLevel(raw, fallback = "low") {
   return LLM_THINKING_LEVELS.has(normalized) ? normalized : fallback;
 }
 
+function firstConfiguredValue(...values) {
+  for (const value of values) {
+    if (value === undefined || value === null) continue;
+    if (typeof value === "string" && !value.trim()) continue;
+    return value;
+  }
+  return "";
+}
+
+function resolveRawLlmModelEntries(config = {}) {
+  if (Array.isArray(config.llmModels) && config.llmModels.length > 0) return config.llmModels;
+  if (Array.isArray(config.models) && config.models.length > 0) return config.models;
+  return [config];
+}
+
+function normalizeScreeningLlmModel(config = {}, rawEntry = {}, index = 0) {
+  const entry = typeof rawEntry === "string"
+    ? { model: rawEntry }
+    : (rawEntry && typeof rawEntry === "object" && !Array.isArray(rawEntry) ? rawEntry : {});
+  return {
+    name: normalizeText(firstConfiguredValue(entry.name, entry.label, entry.id, entry.providerName, entry.provider)),
+    baseUrl: normalizeText(firstConfiguredValue(entry.baseUrl, entry.base_url, config.baseUrl, config.base_url)).replace(/\/+$/, ""),
+    apiKey: normalizeText(firstConfiguredValue(entry.apiKey, entry.api_key, config.apiKey, config.api_key)),
+    model: normalizeText(firstConfiguredValue(entry.model, entry.modelName, entry.model_name, typeof rawEntry === "string" ? rawEntry : "", config.model)),
+    openaiOrganization: normalizeText(firstConfiguredValue(entry.openaiOrganization, entry.organization, config.openaiOrganization, config.organization)),
+    openaiProject: normalizeText(firstConfiguredValue(entry.openaiProject, entry.project, config.openaiProject, config.project)),
+    llmThinkingLevel: normalizeLlmThinkingLevel(
+      firstConfiguredValue(entry.llmThinkingLevel, entry.thinkingLevel, entry.reasoningEffort, config.llmThinkingLevel, config.thinkingLevel, config.reasoningEffort),
+      "low"
+    ),
+    llmTimeoutMs: parsePositiveInteger(firstConfiguredValue(entry.llmTimeoutMs, entry.timeoutMs, config.llmTimeoutMs, config.timeoutMs), null),
+    llmMaxRetries: parsePositiveInteger(firstConfiguredValue(entry.llmMaxRetries, entry.maxRetries, config.llmMaxRetries, config.maxRetries), null),
+    llmMaxTokens: parsePositiveInteger(firstConfiguredValue(entry.llmMaxTokens, entry.maxTokens, config.llmMaxTokens, config.maxTokens), null),
+    llmMaxCompletionTokens: parsePositiveInteger(
+      firstConfiguredValue(entry.llmMaxCompletionTokens, entry.maxCompletionTokens, config.llmMaxCompletionTokens, config.maxCompletionTokens),
+      null
+    ),
+    llmImageLimit: parsePositiveInteger(firstConfiguredValue(entry.llmImageLimit, entry.imageLimit, config.llmImageLimit, config.imageLimit), null),
+    llmImageDetail: normalizeText(firstConfiguredValue(entry.llmImageDetail, entry.imageDetail, config.llmImageDetail, config.imageDetail)),
+    temperature: parseConfigNumber(firstConfiguredValue(entry.temperature, config.temperature), null),
+    topP: parseConfigNumber(firstConfiguredValue(entry.topP, entry.top_p, config.topP, config.top_p), null),
+    llmProviderIndex: index
+  };
+}
+
+function normalizeScreeningLlmModels(config = {}) {
+  return resolveRawLlmModelEntries(config).map((entry, index) => normalizeScreeningLlmModel(config, entry, index));
+}
+
 function resolveConfigPathValue(raw, configDir) {
   const normalized = normalizeText(raw);
   if (!normalized) return "";
@@ -259,13 +308,14 @@ function validateScreeningConfig(config) {
       message: "screening-config.json 缺失或格式无效。请填写 baseUrl、apiKey、model。"
     };
   }
-  const baseUrl = normalizeText(config.baseUrl).replace(/\/+$/, "");
-  const apiKey = normalizeText(config.apiKey);
-  const model = normalizeText(config.model);
+  const llmModels = normalizeScreeningLlmModels(config);
   const missing = [];
-  if (!baseUrl) missing.push("baseUrl");
-  if (!apiKey) missing.push("apiKey");
-  if (!model) missing.push("model");
+  for (const [index, llmModel] of llmModels.entries()) {
+    const prefix = llmModels.length > 1 ? `llmModels[${index}]` : "";
+    if (!llmModel.baseUrl) missing.push(prefix ? `${prefix}.baseUrl` : "baseUrl");
+    if (!llmModel.apiKey) missing.push(prefix ? `${prefix}.apiKey` : "apiKey");
+    if (!llmModel.model) missing.push(prefix ? `${prefix}.model` : "model");
+  }
   if (missing.length > 0) {
     return {
       ok: false,
@@ -273,17 +323,20 @@ function validateScreeningConfig(config) {
       message: `screening-config.json 缺少必填字段：${missing.join(", ")}。`
     };
   }
-  if (/^replace-with/i.test(apiKey) || apiKey === SCREEN_CONFIG_TEMPLATE_DEFAULTS.apiKey) {
+  const placeholderModel = llmModels.find((item) => /^replace-with/i.test(item.apiKey) || item.apiKey === SCREEN_CONFIG_TEMPLATE_DEFAULTS.apiKey);
+  if (placeholderModel) {
     return {
       ok: false,
       reason: "PLACEHOLDER_API_KEY",
       message: "screening-config.json 的 apiKey 仍是模板占位符，请填写真实 API Key。"
     };
   }
+  const firstModel = llmModels[0] || {};
   if (
-    baseUrl === SCREEN_CONFIG_TEMPLATE_DEFAULTS.baseUrl
-    && apiKey === SCREEN_CONFIG_TEMPLATE_DEFAULTS.apiKey
-    && model === SCREEN_CONFIG_TEMPLATE_DEFAULTS.model
+    llmModels.length === 1
+    && firstModel.baseUrl === SCREEN_CONFIG_TEMPLATE_DEFAULTS.baseUrl
+    && firstModel.apiKey === SCREEN_CONFIG_TEMPLATE_DEFAULTS.apiKey
+    && firstModel.model === SCREEN_CONFIG_TEMPLATE_DEFAULTS.model
   ) {
     return {
       ok: false,
@@ -393,24 +446,28 @@ export function resolveBossScreeningConfig(workspaceRoot) {
       candidate_paths: candidatePaths
     };
   }
+  const llmModels = normalizeScreeningLlmModels(parsed);
+  const primaryLlmModel = llmModels[0] || {};
+  const greetingText = normalizeText(
+    parsed.greetingMessage
+    || parsed.greeting_message
+    || parsed.greetingText
+    || parsed.greeting_text
+    || parsed.greeting
+  );
   return {
     ok: true,
     config: {
-      baseUrl: normalizeText(parsed.baseUrl).replace(/\/+$/, ""),
-      apiKey: normalizeText(parsed.apiKey),
-      model: normalizeText(parsed.model),
-      openaiOrganization: normalizeText(parsed.openaiOrganization || parsed.organization),
-      openaiProject: normalizeText(parsed.openaiProject || parsed.project),
+      ...primaryLlmModel,
+      baseUrl: primaryLlmModel.baseUrl,
+      apiKey: primaryLlmModel.apiKey,
+      model: primaryLlmModel.model,
+      openaiOrganization: primaryLlmModel.openaiOrganization,
+      openaiProject: primaryLlmModel.openaiProject,
+      llmModels,
+      greetingMessage: greetingText,
+      greetingText,
       debugPort: parsePositiveInteger(parsed.debugPort, 9222),
-      llmThinkingLevel: normalizeLlmThinkingLevel(parsed.llmThinkingLevel || parsed.thinkingLevel || parsed.reasoningEffort, "low"),
-      llmTimeoutMs: parsePositiveInteger(parsed.llmTimeoutMs || parsed.timeoutMs, null),
-      llmMaxRetries: parsePositiveInteger(parsed.llmMaxRetries || parsed.maxRetries, null),
-      llmMaxTokens: parsePositiveInteger(parsed.llmMaxTokens || parsed.maxTokens, null),
-      llmMaxCompletionTokens: parsePositiveInteger(parsed.llmMaxCompletionTokens || parsed.maxCompletionTokens, null),
-      llmImageLimit: parsePositiveInteger(parsed.llmImageLimit || parsed.imageLimit, null),
-      llmImageDetail: normalizeText(parsed.llmImageDetail || parsed.imageDetail),
-      temperature: parseConfigNumber(parsed.temperature, null),
-      topP: parseConfigNumber(parsed.topP || parsed.top_p, null),
       outputDir: resolveConfigPathValue(parsed.outputDir, configDir),
       humanRestEnabled: parseConfigBoolean(parsed.humanRestEnabled, false)
     },

package/src/cli.js

@@ -57,6 +57,7 @@ const autoSyncSkipCommands = new Set(["install", "install-skill", "where", "help
 const externalMcpTargetsEnv = "BOSS_RECOMMEND_MCP_CONFIG_TARGETS";
 const externalSkillDirsEnv = "BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS";
 const installConfigDefaults = Object.freeze({
+  greetingMessage: "Hi同学，能麻烦发下简历吗？",
   llmThinkingLevel: "low",
   llmMaxTokens: 512,
   llmMaxRetries: 3,
@@ -1431,6 +1432,8 @@ async function setScreeningConfig(options = {}) {
     apiKey,
     model
   };
+  delete nextConfig.llmModels;
+  delete nextConfig.models;
   if (typeof options["thinking-level"] === "string" && options["thinking-level"].trim()) {
     nextConfig.llmThinkingLevel = options["thinking-level"].trim();
   } else if (typeof options.llmThinkingLevel === "string" && options.llmThinkingLevel.trim()) {
@@ -1445,6 +1448,16 @@ async function setScreeningConfig(options = {}) {
   if (typeof options["output-dir"] === "string" && options["output-dir"].trim()) {
     nextConfig.outputDir = options["output-dir"].trim();
   }
+  const greetingMessage = String(
+    options["greeting-message"]
+    ?? options.greetingMessage
+    ?? options.greeting_text
+    ?? options.greetingText
+    ?? ""
+  ).trim();
+  if (greetingMessage) {
+    nextConfig.greetingMessage = greetingMessage;
+  }
   const debugPort = parsePositivePort(options.port || options["debug-port"]);
   if (debugPort) {
     nextConfig.debugPort = debugPort;
@@ -2538,7 +2551,7 @@ function printHelp() {
   console.log("  boss-recommend-mcp run --detached --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json");
   console.log("  boss-recommend-mcp list-jobs --slow-live --port 9222");
   console.log("  boss-recommend-mcp chat prepare-run --slow-live --port 9222    # CDP-only preflight; start runs through MCP start_boss_chat_run");
-  console.log("  boss-recommend-mcp config set --base-url <url> --api-key <key> --model <model> [--thinking-level off|low|medium|high|current] [--openai-organization <id>] [--openai-project <id>]");
+  console.log("  boss-recommend-mcp config set --base-url <url> --api-key <key> --model <model> [--thinking-level off|low|medium|high|current] [--greeting-message <text>] [--openai-organization <id>] [--openai-project <id>]");
   console.log("  boss-recommend-mcp install --agent trae-cn");
   console.log("  boss-recommend-mcp install --agent qclaw    # updates ~/.qclaw/openclaw.json mcp.servers and mirrors skills");
   console.log("  boss-recommend-mcp doctor --agent trae-cn --page-scope featured");

package/src/core/screening/index.js

@@ -58,6 +58,74 @@ function buildChatCompletionsUrl(baseUrl) {
   return `${normalized}/chat/completions`;
 }
 
+function redactBaseUrl(baseUrl) {
+  const normalized = normalizeBaseUrl(baseUrl);
+  return normalized ? normalized.replace(/\/\/[^/]+/, "//[redacted-host]") : "";
+}
+
+function firstConfiguredValue(...values) {
+  for (const value of values) {
+    if (value === undefined || value === null) continue;
+    if (typeof value === "string" && !value.trim()) continue;
+    return value;
+  }
+  return "";
+}
+
+function normalizeLlmProviderEntry(rawEntry, inherited = {}, index = 0) {
+  const entry = typeof rawEntry === "string"
+    ? { model: rawEntry }
+    : (rawEntry && typeof rawEntry === "object" && !Array.isArray(rawEntry) ? rawEntry : {});
+  const providerName = firstConfiguredValue(
+    entry.name,
+    entry.label,
+    entry.id,
+    entry.providerName,
+    entry.provider,
+    ""
+  );
+  const next = {
+    ...inherited,
+    ...entry,
+    baseUrl: firstConfiguredValue(entry.baseUrl, entry.base_url, inherited.baseUrl, inherited.base_url),
+    apiKey: firstConfiguredValue(entry.apiKey, entry.api_key, inherited.apiKey, inherited.api_key),
+    model: firstConfiguredValue(entry.model, entry.modelName, entry.model_name, typeof rawEntry === "string" ? rawEntry : "", inherited.model),
+    openaiOrganization: firstConfiguredValue(entry.openaiOrganization, entry.organization, inherited.openaiOrganization, inherited.organization),
+    openaiProject: firstConfiguredValue(entry.openaiProject, entry.project, inherited.openaiProject, inherited.project),
+    topP: firstConfiguredValue(entry.topP, entry.top_p, inherited.topP, inherited.top_p),
+    llmProviderName: normalizeText(providerName),
+    llmProviderIndex: index
+  };
+  delete next.llmModels;
+  delete next.models;
+  return next;
+}
+
+function normalizeLlmProviderConfigs(config = {}) {
+  if (Array.isArray(config)) {
+    return config.map((entry, index) => normalizeLlmProviderEntry(entry, {}, index));
+  }
+  const inherited = config && typeof config === "object" && !Array.isArray(config) ? { ...config } : {};
+  const rawProviders = Array.isArray(inherited.llmModels) && inherited.llmModels.length > 0
+    ? inherited.llmModels
+    : (Array.isArray(inherited.models) && inherited.models.length > 0 ? inherited.models : [inherited]);
+  delete inherited.llmModels;
+  delete inherited.models;
+  return rawProviders.map((entry, index) => normalizeLlmProviderEntry(entry, inherited, index));
+}
+
+function compactLlmProviderFailure(error, providerConfig = {}, providerIndex = 0) {
+  return {
+    index: providerIndex + 1,
+    name: normalizeText(providerConfig.llmProviderName || providerConfig.name || providerConfig.label || providerConfig.id) || null,
+    baseUrl: redactBaseUrl(providerConfig.baseUrl),
+    model: normalizeText(providerConfig.model) || null,
+    status: Number.isFinite(Number(error?.status)) ? Number(error.status) : null,
+    attempts: Number(error?.llm_attempt_count) || 0,
+    message: String(error?.message || error || "").slice(0, 500)
+  };
+}
+
 function isVolcengineModel(baseUrl, model) {
   return /volces|volcengine|ark\.cn|doubao|seed/i.test(`${baseUrl || ""} ${model || ""}`);
 }
@@ -1325,6 +1393,8 @@ export function compactScreeningLlmResult(llmResult) {
     finish_reason: llmResult.finish_reason || null,
     image_input_count: llmResult.image_input_count || 0,
     attempt_count: llmResult.attempt_count || 0,
+    fallback_count: llmResult.fallback_count || 0,
+    llm_model_failures: Array.isArray(llmResult.llm_model_failures) ? llmResult.llm_model_failures : [],
     error: llmResult.error || null,
     screened_at: llmResult.screened_at || null
   };
@@ -1358,6 +1428,8 @@ export function createFailedLlmScreeningResult(error) {
     image_input_count: Number(error?.image_input_count) || 0,
     image_inputs: Array.isArray(error?.image_inputs) ? error.image_inputs : [],
     attempt_count: Number(error?.llm_attempt_count) || 0,
+    fallback_count: Array.isArray(error?.llm_model_failures) ? error.llm_model_failures.length : 0,
+    llm_model_failures: Array.isArray(error?.llm_model_failures) ? error.llm_model_failures : [],
     error: error?.message || String(error || "unknown"),
     screened_at: nowIso()
   };
@@ -1435,7 +1507,7 @@ function sleepMs(ms) {
   return new Promise((resolve) => setTimeout(resolve, Math.max(0, Number(ms) || 0)));
 }
 
-export async function callScreeningLlm({
+async function callScreeningLlmWithProvider({
   candidate,
   criteria,
   config = {},
@@ -1488,81 +1560,89 @@ export async function callScreeningLlm({
     thinkingLevel
   });
 
+  const effectiveTimeoutMs = parsePositiveNumber(config.llmTimeoutMs ?? config.timeoutMs, timeoutMs) || timeoutMs;
   const maxRetries = normalizeLlmMaxRetries(config.llmMaxRetries ?? config.maxRetries);
   const maxAttempts = maxRetries + 1;
   let lastError = null;
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = setTimeout(() => controller.abort(), effectiveTimeoutMs);
     try {
-    const headers = {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${apiKey}`
-    };
-    if (config.openaiOrganization) headers["OpenAI-Organization"] = config.openaiOrganization;
-    if (config.openaiProject) headers["OpenAI-Project"] = config.openaiProject;
-
-    const response = await fetch(buildChatCompletionsUrl(baseUrl), {
-      method: "POST",
-      headers,
-      body: JSON.stringify(payload),
-      signal: controller.signal
-    });
-    const responseText = await response.text();
-    if (!response.ok) {
-      const error = new Error(`LLM request failed: ${response.status} ${responseText.slice(0, 400)}`);
-      error.status = response.status;
-      throw error;
-    }
-    const json = tryParseJson(responseText);
-    if (!json) {
-      throw new Error("LLM response was not valid JSON");
-    }
-    const choice = json?.choices?.[0] || {};
-    const content = flattenChatMessageContent(choice?.message?.content);
-    const reasoningContent = collectLlmReasoningText(choice);
-    const parsed = tryExtractJsonObject(content) || tryExtractJsonObject(reasoningContent);
-    const passed = parsePassedDecision(parsed?.passed);
-    if (passed === null) {
-      throw new Error(`LLM response missing boolean passed decision: ${content.slice(0, 240)}`);
-    }
-    const evidence = Array.isArray(parsed?.evidence)
-      ? parsed.evidence.map(normalizeText).filter(Boolean)
-      : [];
-    const decisionCot = firstUsefulLine([
-      parsed?.cot,
-      parsed?.decision_cot,
-      parsed?.reasoning,
-      parsed?.chain_of_thought,
-      reasoningContent
-    ].map(normalizeBlockText).filter(Boolean)) || reasoningContent;
-    return {
-      ok: true,
-      provider: {
-        baseUrl: baseUrl.replace(/\/\/[^/]+/, "//[redacted-host]"),
-        model,
-        thinking_level: normalizeLlmThinkingLevel(thinkingLevel) || "low",
-        thinking: payload.thinking || null,
-        reasoning_effort: payload.reasoning_effort || null,
-        max_tokens: payload.max_tokens,
-        max_completion_tokens: payload.max_completion_tokens || null
-      },
-      passed,
-      reason: "",
-      evidence,
-      cot: decisionCot,
-      decision_cot: decisionCot,
-      reasoning_content: reasoningContent,
-      raw_model_output: content,
-      usage: json.usage || null,
-      finish_reason: choice.finish_reason || null,
-      raw_content_length: content.length,
-      image_input_count: imageInputs.length,
-      image_inputs: summarizeLlmImageInputs(imageInputs),
-      attempt_count: attempt,
-      screened_at: nowIso()
-    };
-  } catch (error) {
+      const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      };
+      if (config.openaiOrganization) headers["OpenAI-Organization"] = config.openaiOrganization;
+      if (config.openaiProject) headers["OpenAI-Project"] = config.openaiProject;
+
+      const response = await fetch(buildChatCompletionsUrl(baseUrl), {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      const responseText = await response.text();
+      if (!response.ok) {
+        const error = new Error(`LLM request failed: ${response.status} ${responseText.slice(0, 400)}`);
+        error.status = response.status;
+        throw error;
+      }
+      const json = tryParseJson(responseText);
+      if (!json) {
+        throw new Error("LLM response was not valid JSON");
+      }
+      const choice = json?.choices?.[0] || {};
+      const content = flattenChatMessageContent(choice?.message?.content);
+      const reasoningContent = collectLlmReasoningText(choice);
+      const parsed = tryExtractJsonObject(content) || tryExtractJsonObject(reasoningContent);
+      const passed = parsePassedDecision(parsed?.passed);
+      if (passed === null) {
+        throw new Error(`LLM response missing boolean passed decision: ${content.slice(0, 240)}`);
+      }
+      const evidence = Array.isArray(parsed?.evidence)
+        ? parsed.evidence.map(normalizeText).filter(Boolean)
+        : [];
+      const decisionCot = firstUsefulLine([
+        parsed?.cot,
+        parsed?.decision_cot,
+        parsed?.reasoning,
+        parsed?.chain_of_thought,
+        reasoningContent
+      ].map(normalizeBlockText).filter(Boolean)) || reasoningContent;
+      const providerName = normalizeText(config.llmProviderName || config.name || config.label || config.id);
+      const providerIndex = Number.isFinite(Number(config.llmProviderIndex)) ? Number(config.llmProviderIndex) : 0;
+      const providerCount = Number.isFinite(Number(config.llmProviderCount)) ? Number(config.llmProviderCount) : 1;
+      return {
+        ok: true,
+        provider: {
+          baseUrl: redactBaseUrl(baseUrl),
+          model,
+          name: providerName || null,
+          index: providerIndex + 1,
+          total: providerCount,
+          thinking_level: normalizeLlmThinkingLevel(thinkingLevel) || "low",
+          thinking: payload.thinking || null,
+          reasoning_effort: payload.reasoning_effort || null,
+          max_tokens: payload.max_tokens,
+          max_completion_tokens: payload.max_completion_tokens || null
+        },
+        passed,
+        reason: "",
+        evidence,
+        cot: decisionCot,
+        decision_cot: decisionCot,
+        reasoning_content: reasoningContent,
+        raw_model_output: content,
+        usage: json.usage || null,
+        finish_reason: choice.finish_reason || null,
+        raw_content_length: content.length,
+        image_input_count: imageInputs.length,
+        image_inputs: summarizeLlmImageInputs(imageInputs),
+        attempt_count: attempt,
+        provider_attempt_count: attempt,
+        screened_at: nowIso()
+      };
+    } catch (error) {
       lastError = error;
       if (attempt >= maxAttempts || !isRetryableLlmRequestError(error)) {
         error.image_input_count = imageInputs.length;
@@ -1571,9 +1651,9 @@ export async function callScreeningLlm({
         throw error;
       }
       await sleepMs(Math.min(2500, 500 * attempt));
-  } finally {
-    clearTimeout(timer);
-  }
+    } finally {
+      clearTimeout(timer);
+    }
   }
   lastError = lastError || new Error("LLM request failed without response");
   lastError.image_input_count = imageInputs.length;
@@ -1581,3 +1661,58 @@ export async function callScreeningLlm({
   lastError.llm_attempt_count = maxAttempts;
   throw lastError;
 }
+
+export async function callScreeningLlm(args = {}) {
+  const providers = normalizeLlmProviderConfigs(args.config || {});
+  if (providers.length <= 1) {
+    return callScreeningLlmWithProvider({
+      ...args,
+      config: {
+        ...(providers[0] || args.config || {}),
+        llmProviderCount: 1
+      }
+    });
+  }
+
+  const providerFailures = [];
+  let lastError = null;
+  for (let index = 0; index < providers.length; index += 1) {
+    const providerConfig = {
+      ...providers[index],
+      llmProviderIndex: index,
+      llmProviderCount: providers.length
+    };
+    try {
+      const previousAttempts = providerFailures.reduce((sum, item) => sum + (Number(item.attempts) || 0), 0);
+      const result = await callScreeningLlmWithProvider({
+        ...args,
+        config: providerConfig
+      });
+      const providerAttempts = Number(result.provider_attempt_count ?? result.attempt_count) || 0;
+      return {
+        ...result,
+        attempt_count: previousAttempts + providerAttempts,
+        llm_model_failures: providerFailures,
+        fallback_count: providerFailures.length
+      };
+    } catch (error) {
+      lastError = error;
+      providerFailures.push(compactLlmProviderFailure(error, providerConfig, index));
+      if (index < providers.length - 1) {
+        await sleepMs(Math.min(1500, 250 * (index + 1)));
+      }
+    }
+  }
+
+  const totalAttempts = providerFailures.reduce((sum, item) => sum + (Number(item.attempts) || 0), 0);
+  const finalError = new Error(
+    `All configured LLM models failed (${providers.length}); last error: ${lastError?.message || "unknown error"}`
+  );
+  finalError.cause = lastError || null;
+  finalError.llm_provider_failures = providerFailures;
+  finalError.llm_model_failures = providerFailures;
+  finalError.llm_attempt_count = totalAttempts;
+  finalError.image_input_count = lastError?.image_input_count || 0;
+  finalError.image_inputs = lastError?.image_inputs || [];
+  throw finalError;
+}

package/src/domains/chat/run-service.js

@@ -109,6 +109,8 @@ function compactLlmResult(llmResult) {
     finish_reason: llmResult.finish_reason || null,
     image_input_count: llmResult.image_input_count || 0,
     attempt_count: llmResult.attempt_count || 0,
+    fallback_count: llmResult.fallback_count || 0,
+    llm_model_failures: Array.isArray(llmResult.llm_model_failures) ? llmResult.llm_model_failures : [],
     error: llmResult.error || null
   };
 }
@@ -287,6 +289,9 @@ function createFailedLlmResult(error) {
     decision_cot: "",
     reasoning_content: "",
     raw_model_output: "",
+    attempt_count: Number(error?.llm_attempt_count) || 0,
+    fallback_count: Array.isArray(error?.llm_model_failures) ? error.llm_model_failures.length : 0,
+    llm_model_failures: Array.isArray(error?.llm_model_failures) ? error.llm_model_failures : [],
     error: error?.message || String(error || "unknown"),
     screened_at: new Date().toISOString()
   };
@@ -1638,6 +1643,7 @@ export function createChatRunService({
         close_resume: closeResume,
         request_resume_for_passed: Boolean(requestResumeForPassed),
         dry_run_request_cv: Boolean(dryRunRequestCv),
+        greeting_text: greetingText,
         cv_acquisition_mode: cvAcquisitionMode,
         call_llm_on_image: Boolean(callLlmOnImage),
         screening_mode: normalizedScreeningMode,

package/src/domains/recommend/run-service.js

@@ -41,6 +41,7 @@ import {
   closeRecommendDetail,
   createRecommendDetailNetworkRecorder,
   extractRecommendDetailCandidate,
+  isStaleRecommendNodeError,
   openRecommendCardDetailWithFreshRetry,
   waitForRecommendDetailNetworkEvents
 } from "./detail.js";
@@ -381,6 +382,7 @@ function compactError(error, fallbackCode = "RECOMMEND_RUN_ERROR") {
 export function isRecoverableImageCaptureError(error) {
   const code = String(error?.code || "");
   if (code === "IMAGE_CAPTURE_TIMEOUT" || code === "IMAGE_CAPTURE_TOTAL_TIMEOUT") return true;
+  if (isStaleRecommendNodeError(error)) return true;
   return /Image fallback capture timed out/i.test(String(error?.message || error || ""));
 }
 
@@ -420,7 +422,7 @@ export function createRecoverableImageCaptureEvidence(error, {
     llm_total_byte_length: 0,
     llm_original_total_byte_length: 0,
     llm_composition_error: null,
-    error_code: error?.code || "IMAGE_CAPTURE_FAILED",
+    error_code: error?.code || (isStaleRecommendNodeError(error) ? "IMAGE_CAPTURE_STALE_NODE" : "IMAGE_CAPTURE_FAILED"),
     error: error?.message || String(error || "Image capture failed"),
     file_paths: filePaths,
     llm_file_paths: []
@@ -438,6 +440,27 @@ function createImageCaptureFailureScreening(candidate, error) {
   };
 }
 
+export function isRecoverableRecommendDetailError(error) {
+  return isStaleRecommendNodeError(error);
+}
+
+function compactRecoverableDetailError(error) {
+  return compactError(error, isStaleRecommendNodeError(error) ? "DETAIL_STALE_NODE" : "DETAIL_OPEN_FAILED");
+}
+
+function createRecoverableDetailFailureScreening(candidate, error) {
+  return {
+    status: "fail",
+    passed: false,
+    score: 0,
+    reasons: isStaleRecommendNodeError(error)
+      ? ["detail_open_failed", "stale_node"]
+      : ["detail_open_failed"],
+    error: compactRecoverableDetailError(error),
+    candidate
+  };
+}
+
 export async function runRecommendWorkflow({
   client,
   targetUrl = "",
@@ -746,139 +769,149 @@ export async function runRecommendWorkflow({
 
     let screeningCandidate = cardCandidate;
     let detailResult = null;
+    let recoverableDetailError = null;
     if (index < effectiveDetailLimit) {
-      await runControl.waitIfPaused();
-      runControl.throwIfCanceled();
-      runControl.setPhase("recommend:detail");
-      rootState = await ensureRecommendViewport(rootState, "detail");
-      networkRecorder.clear();
-      const openedDetail = await openRecommendCardDetailWithFreshRetry(client, {
-        cardNodeId,
-        candidateKey,
-        cardCandidate,
-        rootState,
-        targetUrl,
-        maxAttempts: 2
-      });
-      addTiming(timings, "candidate_click_ms", openedDetail.timings?.candidate_click_ms);
-      addTiming(timings, "detail_open_ms", openedDetail.timings?.detail_open_ms);
-      cardNodeId = openedDetail.card_node_id || cardNodeId;
-      cardCandidate = openedDetail.card_candidate || cardCandidate;
-      screeningCandidate = cardCandidate;
-      const waitPlan = getCvNetworkWaitPlan(cvAcquisitionState);
-      const networkWait = await measureTiming(timings, "network_cv_wait_ms", () => waitForCvNetworkEvents(
-        waitForRecommendDetailNetworkEvents,
-        networkRecorder,
-        {
-          waitPlan,
-          minCount: 1,
-          requireLoaded: true,
-          intervalMs: 120
-        }
-      ));
-      if (networkWait?.elapsed_ms != null) {
-        timings.network_cv_wait_ms = Math.round(Number(networkWait.elapsed_ms) || 0);
-      }
-      detailResult = await extractRecommendDetailCandidate(client, {
-        cardCandidate,
-        cardNodeId,
-        detailState: openedDetail.detail_state,
-        networkEvents: networkRecorder.events,
-        targetUrl,
-        closeDetail: false,
-        networkParseRetryMs: waitPlan.mode_before === "image" ? 500 : 2200,
-        networkParseIntervalMs: 250
-      });
-      addTiming(timings, "late_network_retry_ms", detailResult.network_parse_retry_elapsed_ms);
-
-      const parsedNetworkProfileCount = countParsedNetworkProfiles(detailResult);
-      let source = "network";
-      let imageEvidence = null;
-      if (parsedNetworkProfileCount > 0) {
-        recordCvNetworkHit(cvAcquisitionState, {
-          parsedNetworkProfileCount,
-          waitResult: networkWait
+      try {
+        await runControl.waitIfPaused();
+        runControl.throwIfCanceled();
+        runControl.setPhase("recommend:detail");
+        rootState = await ensureRecommendViewport(rootState, "detail");
+        networkRecorder.clear();
+        const openedDetail = await openRecommendCardDetailWithFreshRetry(client, {
+          cardNodeId,
+          candidateKey,
+          cardCandidate,
+          rootState,
+          targetUrl,
+          retryTimeoutMs: 8000,
+          maxAttempts: 3
         });
-      } else {
-        const captureNodeId = openedDetail.detail_state?.popup?.node_id
-          || openedDetail.detail_state?.resumeIframe?.node_id
-          || null;
-        if (captureNodeId) {
-          const imageEvidencePath = imageEvidenceFilePath({
-            imageOutputDir,
-            domain: "recommend",
-            runId: runControl?.runId,
-            index,
-            extension: "jpg"
-          });
-          try {
-            imageEvidence = await measureTiming(timings, "screenshot_capture_ms", () => captureScrolledNodeScreenshots(client, captureNodeId, {
-              filePath: imageEvidencePath,
-              format: "jpeg",
-              quality: 72,
-              optimize: true,
-              resizeMaxWidth: 1100,
-              captureViewport: true,
-              padding: 4,
-              maxScreenshots: maxImagePages,
-              wheelDeltaY: imageWheelDeltaY,
-              settleMs: 350,
-              scrollMethod: "dom-anchor-fallback-input",
-              stepTimeoutMs: 45000,
-              totalTimeoutMs: 90000,
-              duplicateStopCount: 1,
-              skipDuplicateScreenshots: true,
-              composeForLlm: true,
-              llmPagesPerImage: 3,
-              llmResizeMaxWidth: 1100,
-              llmQuality: 72,
-              metadata: {
-                domain: "recommend",
-                capture_mode: "scroll_sequence",
-                acquisition_reason: "network_miss_image_fallback",
-                run_candidate_index: index,
-                candidate_key: candidateKey
-              }
-            }));
-            source = "image";
-          } catch (error) {
-            if (!isRecoverableImageCaptureError(error)) throw error;
-            imageEvidence = createRecoverableImageCaptureEvidence(error, {
-              elapsedMs: timings.screenshot_capture_ms,
-              filePath: imageEvidencePath,
-              extension: "jpg",
-              maxScreenshots: maxImagePages
-            });
-            source = "image_capture_failed";
+        addTiming(timings, "candidate_click_ms", openedDetail.timings?.candidate_click_ms);
+        addTiming(timings, "detail_open_ms", openedDetail.timings?.detail_open_ms);
+        cardNodeId = openedDetail.card_node_id || cardNodeId;
+        cardCandidate = openedDetail.card_candidate || cardCandidate;
+        screeningCandidate = cardCandidate;
+        const waitPlan = getCvNetworkWaitPlan(cvAcquisitionState);
+        const networkWait = await measureTiming(timings, "network_cv_wait_ms", () => waitForCvNetworkEvents(
+          waitForRecommendDetailNetworkEvents,
+          networkRecorder,
+          {
+            waitPlan,
+            minCount: 1,
+            requireLoaded: true,
+            intervalMs: 120
           }
-          recordCvImageFallback(cvAcquisitionState, {
-            reason: source === "image_capture_failed"
-              ? "network_miss_image_capture_failed"
-              : "network_miss_image_fallback",
-            parsedNetworkProfileCount,
-            waitResult: networkWait,
-            imageEvidence
-          });
-        } else {
-          source = "missing_capture_node";
-          recordCvNetworkMiss(cvAcquisitionState, {
-            reason: "network_miss_no_capture_node",
+        ));
+        if (networkWait?.elapsed_ms != null) {
+          timings.network_cv_wait_ms = Math.round(Number(networkWait.elapsed_ms) || 0);
+        }
+        detailResult = await extractRecommendDetailCandidate(client, {
+          cardCandidate,
+          cardNodeId,
+          detailState: openedDetail.detail_state,
+          networkEvents: networkRecorder.events,
+          targetUrl,
+          closeDetail: false,
+          networkParseRetryMs: waitPlan.mode_before === "image" ? 500 : 2200,
+          networkParseIntervalMs: 250
+        });
+        addTiming(timings, "late_network_retry_ms", detailResult.network_parse_retry_elapsed_ms);
+
+        const parsedNetworkProfileCount = countParsedNetworkProfiles(detailResult);
+        let source = "network";
+        let imageEvidence = null;
+        if (parsedNetworkProfileCount > 0) {
+          recordCvNetworkHit(cvAcquisitionState, {
             parsedNetworkProfileCount,
             waitResult: networkWait
           });
+        } else {
+          const captureNodeId = openedDetail.detail_state?.popup?.node_id
+            || openedDetail.detail_state?.resumeIframe?.node_id
+            || null;
+          if (captureNodeId) {
+            const imageEvidencePath = imageEvidenceFilePath({
+              imageOutputDir,
+              domain: "recommend",
+              runId: runControl?.runId,
+              index,
+              extension: "jpg"
+            });
+            try {
+              imageEvidence = await measureTiming(timings, "screenshot_capture_ms", () => captureScrolledNodeScreenshots(client, captureNodeId, {
+                filePath: imageEvidencePath,
+                format: "jpeg",
+                quality: 72,
+                optimize: true,
+                resizeMaxWidth: 1100,
+                captureViewport: true,
+                padding: 4,
+                maxScreenshots: maxImagePages,
+                wheelDeltaY: imageWheelDeltaY,
+                settleMs: 350,
+                scrollMethod: "dom-anchor-fallback-input",
+                stepTimeoutMs: 45000,
+                totalTimeoutMs: 90000,
+                duplicateStopCount: 1,
+                skipDuplicateScreenshots: true,
+                composeForLlm: true,
+                llmPagesPerImage: 3,
+                llmResizeMaxWidth: 1100,
+                llmQuality: 72,
+                metadata: {
+                  domain: "recommend",
+                  capture_mode: "scroll_sequence",
+                  acquisition_reason: "network_miss_image_fallback",
+                  run_candidate_index: index,
+                  candidate_key: candidateKey
+                }
+              }));
+              source = "image";
+            } catch (error) {
+              if (!isRecoverableImageCaptureError(error)) throw error;
+              imageEvidence = createRecoverableImageCaptureEvidence(error, {
+                elapsedMs: timings.screenshot_capture_ms,
+                filePath: imageEvidencePath,
+                extension: "jpg",
+                maxScreenshots: maxImagePages
+              });
+              source = "image_capture_failed";
+            }
+            recordCvImageFallback(cvAcquisitionState, {
+              reason: source === "image_capture_failed"
+                ? "network_miss_image_capture_failed"
+                : "network_miss_image_fallback",
+              parsedNetworkProfileCount,
+              waitResult: networkWait,
+              imageEvidence
+            });
+          } else {
+            source = "missing_capture_node";
+            recordCvNetworkMiss(cvAcquisitionState, {
+              reason: "network_miss_no_capture_node",
+              parsedNetworkProfileCount,
+              waitResult: networkWait
+            });
+          }
         }
-      }
 
-      detailResult.image_evidence = imageEvidence;
-      detailResult.cv_acquisition = {
-        source,
-        mode_after: compactCvAcquisitionState(cvAcquisitionState).mode,
-        wait_plan: waitPlan,
-        network_wait: networkWait,
-        parsed_network_profile_count: parsedNetworkProfileCount,
-        image_evidence: summarizeImageEvidence(imageEvidence)
-      };
-      screeningCandidate = detailResult.candidate;
+        detailResult.image_evidence = imageEvidence;
+        detailResult.cv_acquisition = {
+          source,
+          mode_after: compactCvAcquisitionState(cvAcquisitionState).mode,
+          wait_plan: waitPlan,
+          network_wait: networkWait,
+          parsed_network_profile_count: parsedNetworkProfileCount,
+          image_evidence: summarizeImageEvidence(imageEvidence)
+        };
+        screeningCandidate = detailResult.candidate;
+      } catch (error) {
+        if (!isRecoverableRecommendDetailError(error)) throw error;
+        recoverableDetailError = error;
+        detailResult = null;
+        timings.detail_recovered_error = compactRecoverableDetailError(error);
+        await closeRecommendDetail(client, { attemptsLimit: 2 }).catch(() => null);
+      }
     }
 
     await runControl.waitIfPaused();
@@ -886,7 +919,7 @@ export async function runRecommendWorkflow({
     runControl.setPhase("recommend:screening");
     let llmResult = null;
     if (useLlmScreening) {
-      if (detailResult?.image_evidence?.ok === false) {
+      if (recoverableDetailError || detailResult?.image_evidence?.ok === false) {
         llmResult = null;
       } else if (!llmConfig) {
         llmResult = createMissingLlmConfigResult();
@@ -910,7 +943,9 @@ export async function runRecommendWorkflow({
       }
       if (detailResult) detailResult.llm_result = llmResult;
     }
-    const screening = detailResult?.image_evidence?.ok === false
+    const screening = recoverableDetailError
+      ? createRecoverableDetailFailureScreening(screeningCandidate, recoverableDetailError)
+      : detailResult?.image_evidence?.ok === false
       ? createImageCaptureFailureScreening(screeningCandidate, {
         code: detailResult.image_evidence.error_code,
         message: detailResult.image_evidence.error
@@ -959,7 +994,9 @@ export async function runRecommendWorkflow({
       screening: compactScreening(screening),
       action_discovery: compactActionDiscovery(actionDiscovery),
       post_action: postActionResult,
-      error: detailResult?.image_evidence?.ok === false
+      error: recoverableDetailError
+        ? compactRecoverableDetailError(recoverableDetailError)
+        : detailResult?.image_evidence?.ok === false
         ? compactError({
           code: detailResult.image_evidence.error_code,
           message: detailResult.image_evidence.error
@@ -987,6 +1024,8 @@ export async function runRecommendWorkflow({
       greet_count: greetCount,
       post_action_clicked: results.filter((item) => item.post_action?.action_clicked).length,
       image_capture_failed: results.filter((item) => item.detail?.image_evidence?.ok === false).length,
+      detail_open_failed: results.filter((item) => item.error?.code === "DETAIL_STALE_NODE" || item.error?.code === "DETAIL_OPEN_FAILED").length,
+      transient_recovered: results.filter((item) => item.error?.code === "DETAIL_STALE_NODE" || item.error?.code === "IMAGE_CAPTURE_STALE_NODE" || item.error?.code === "IMAGE_CAPTURE_TIMEOUT" || item.error?.code === "IMAGE_CAPTURE_TOTAL_TIMEOUT").length,
       unique_seen: compactInfiniteListState(listState).seen_count,
       scroll_count: compactInfiniteListState(listState).scroll_count,
       refresh_rounds: refreshRounds,
@@ -1050,6 +1089,9 @@ export async function runRecommendWorkflow({
     screened: results.length,
     detail_opened: results.filter((item) => item.detail).length,
     llm_screened: results.filter((item) => item.detail?.llm_screening || item.llm_screening).length,
+    detail_open_failed: results.filter((item) => item.error?.code === "DETAIL_STALE_NODE" || item.error?.code === "DETAIL_OPEN_FAILED").length,
+    image_capture_failed: results.filter((item) => item.detail?.image_evidence?.ok === false).length,
+    transient_recovered: results.filter((item) => item.error?.code === "DETAIL_STALE_NODE" || item.error?.code === "IMAGE_CAPTURE_STALE_NODE" || item.error?.code === "IMAGE_CAPTURE_TIMEOUT" || item.error?.code === "IMAGE_CAPTURE_TOTAL_TIMEOUT").length,
     passed: results.filter((item) => item.screening.passed).length,
     greet_count: greetCount,
     post_action_clicked: results.filter((item) => item.post_action?.action_clicked).length,

package/src/recommend-mcp.js

@@ -288,6 +288,66 @@ function completionReason(status) {
   return null;
 }
 
+function normalizeErrorText(error = {}) {
+  return normalizeText([
+    error?.code || "",
+    error?.message || error || ""
+  ].join(" "));
+}
+
+function classifyRecommendRecovery(error = {}) {
+  const text = normalizeErrorText(error);
+  if (!text) return null;
+  if (/BOSS_LOGIN_REQUIRED/i.test(text)) return "login_required";
+  if (/Could not find node with given id|No node with given id|Node is detached|Cannot find node|DETAIL_STALE_NODE|IMAGE_CAPTURE_STALE_NODE/i.test(text)) {
+    return "transient_stale_dom";
+  }
+  if (/IMAGE_CAPTURE_TIMEOUT|IMAGE_CAPTURE_TOTAL_TIMEOUT|Image fallback capture timed out/i.test(text)) {
+    return "transient_image_capture";
+  }
+  if (/(?:aborted|abort|timeout|timed out|fetch failed|socket|network|ECONNRESET|ETIMEDOUT|EAI_AGAIN)/i.test(text)) {
+    return "transient_network_or_llm";
+  }
+  return null;
+}
+
+function buildConstrainedAgentRecovery(snapshot = {}, meta = {}, artifacts = null) {
+  const error = snapshot?.error || snapshot?.result?.error || null;
+  const classification = classifyRecommendRecovery(error);
+  if (!classification) return null;
+  const canRestartSameRequest = classification !== "login_required";
+  return {
+    policy_version: 1,
+    classification,
+    safe_for_outer_ai_agent: true,
+    recommended_action: canRestartSameRequest
+      ? "restart_same_recommend_request_only"
+      : "ask_user_to_login_then_retry_same_recommend_request",
+    package_requirement: "@reconcrap/boss-recommend-mcp@>=2.0.30",
+    run_id: snapshot?.runId || snapshot?.run_id || null,
+    retryable: true,
+    same_request_sources: {
+      instruction: "run.context.instruction",
+      confirmation: "run.context.confirmation",
+      overrides: "run.context.overrides",
+      follow_up: "run.context.follow_up"
+    },
+    constraints: [
+      "Do not change instruction, criteria, filters, job, page_scope, target_count, post_action, or max_greet_count.",
+      "Do not switch to search/recruit/chat and do not add follow_up.chat.",
+      "Do not summarize, translate, or rewrite criteria.",
+      "Do not ask the user to reconfirm business choices unless Boss login is required or the stored context is missing.",
+      "Use the same Chrome debug port and recommend page route."
+    ],
+    artifacts: artifacts ? {
+      run_state_path: artifacts.run_state_path || null,
+      checkpoint_path: artifacts.checkpoint_path || null,
+      report_json: artifacts.report_json || null,
+      output_csv: artifacts.output_csv || null
+    } : null
+  };
+}
+
 function ensureRecommendRunArtifacts(snapshot) {
   const artifacts = getRecommendRunArtifacts(snapshot?.runId || snapshot?.run_id);
   if (!artifacts) return null;
@@ -319,6 +379,7 @@ function ensureRecommendRunArtifacts(snapshot) {
       checkpoint,
       error: snapshot.error || null,
       last_message: snapshot.error?.message || snapshot.phase || snapshot.stage || null,
+      recovery: buildConstrainedAgentRecovery(snapshot, meta, artifacts),
       summary: artifactSummary,
       generated_at: new Date().toISOString()
     });
@@ -397,6 +458,7 @@ function buildLegacyRecommendResult(snapshot) {
     screen_params: clonePlain(meta.parsed?.screenParams || {}, {}),
     target_count_semantics: TARGET_COUNT_SEMANTICS,
     error: snapshot.error || null,
+    recovery: buildConstrainedAgentRecovery(snapshot, meta, artifacts),
     results: resultRows
   };
 }
@@ -411,6 +473,7 @@ function normalizeRunSnapshot(snapshot) {
     TERMINAL_STATUSES.has(snapshot.status)
     || snapshot.status === RUN_STATUS_PAUSED
   ) ? buildLegacyRecommendResult({ ...snapshot, progress }) : null;
+  const recovery = buildConstrainedAgentRecovery(snapshot, meta, artifacts);
   const oldContext = {
     workspace_root: meta.workspaceRoot || null,
     instruction: meta.args?.instruction || "",
@@ -451,6 +514,7 @@ function normalizeRunSnapshot(snapshot) {
       last_resumed_at: meta.lastResumedAt || null,
       last_paused_at: snapshot.status === RUN_STATUS_PAUSED ? snapshot.updatedAt : null
     },
+    recovery,
     result: legacyResult,
     artifacts
   };
@@ -483,6 +547,7 @@ function persistRecommendRunSnapshot(snapshot, {
     control: normalized.control,
     resume: normalized.resume,
     error: normalized.error,
+    recovery: normalized.recovery,
     result: normalized.result,
     summary: normalized.summary,
     artifacts: normalized.artifacts