@reconcrap/boss-recommend-mcp 2.0.28 → 2.0.30

package/package.json

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

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

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import { createRunLifecycleManager } from "../../core/run/index.js";
 import {
   addTiming,
@@ -39,6 +41,7 @@ import {
   closeRecommendDetail,
   createRecommendDetailNetworkRecorder,
   extractRecommendDetailCandidate,
+  isStaleRecommendNodeError,
   openRecommendCardDetailWithFreshRetry,
   waitForRecommendDetailNetworkEvents
 } from "./detail.js";
@@ -376,6 +379,88 @@ 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 || ""));
+}
+
+function collectPartialImageEvidencePaths(basePath = "", extension = "jpg", maxCount = 12) {
+  const resolved = String(basePath || "").trim();
+  if (!resolved) return [];
+  const parsed = path.parse(resolved);
+  const ext = parsed.ext || `.${String(extension || "jpg").replace(/^\./, "") || "jpg"}`;
+  const files = [];
+  for (let index = 0; index < Math.max(1, Number(maxCount) || 1); index += 1) {
+    const page = String(index + 1).padStart(2, "0");
+    const candidatePath = path.join(parsed.dir, `${parsed.name}-page-${page}${ext}`);
+    if (fs.existsSync(candidatePath)) files.push(candidatePath);
+  }
+  return files;
+}
+
+export function createRecoverableImageCaptureEvidence(error, {
+  elapsedMs = 0,
+  filePath = "",
+  extension = "jpg",
+  maxScreenshots = 8
+} = {}) {
+  const filePaths = collectPartialImageEvidencePaths(filePath, extension, maxScreenshots);
+  return {
+    schema_version: 1,
+    ok: false,
+    source: "image-scroll-sequence",
+    elapsed_ms: Math.max(0, Math.round(Number(error?.elapsed_ms ?? elapsedMs) || 0)),
+    capture_count: filePaths.length,
+    screenshot_count: filePaths.length,
+    unique_screenshot_count: filePaths.length,
+    dropped_duplicate_count: 0,
+    total_byte_length: 0,
+    original_total_byte_length: 0,
+    llm_screenshot_count: 0,
+    llm_total_byte_length: 0,
+    llm_original_total_byte_length: 0,
+    llm_composition_error: null,
+    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: []
+  };
+}
+
+function createImageCaptureFailureScreening(candidate, error) {
+  return {
+    status: "fail",
+    passed: false,
+    score: 0,
+    reasons: ["image_capture_failed"],
+    error: compactError(error, "IMAGE_CAPTURE_FAILED"),
+    candidate
+  };
+}
+
+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 = "",
@@ -684,124 +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
+      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
+        });
+        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);
         }
-      ));
-      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
+        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
         });
-      } else {
-        const captureNodeId = openedDetail.detail_state?.popup?.node_id
-          || openedDetail.detail_state?.resumeIframe?.node_id
-          || null;
-        if (captureNodeId) {
-          imageEvidence = await measureTiming(timings, "screenshot_capture_ms", () => captureScrolledNodeScreenshots(client, captureNodeId, {
-            filePath: imageEvidenceFilePath({
+        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"
-            }),
-            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
+            });
+            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";
             }
-          }));
-          source = "image";
-          recordCvImageFallback(cvAcquisitionState, {
-            parsedNetworkProfileCount,
-            waitResult: networkWait,
-            imageEvidence
-          });
-        } else {
-          source = "missing_capture_node";
-          recordCvNetworkMiss(cvAcquisitionState, {
-            reason: "network_miss_no_capture_node",
-            parsedNetworkProfileCount,
-            waitResult: networkWait
-          });
+            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();
@@ -809,7 +919,9 @@ export async function runRecommendWorkflow({
     runControl.setPhase("recommend:screening");
     let llmResult = null;
     if (useLlmScreening) {
-      if (!llmConfig) {
+      if (recoverableDetailError || detailResult?.image_evidence?.ok === false) {
+        llmResult = null;
+      } else if (!llmConfig) {
         llmResult = createMissingLlmConfigResult();
       } else {
         try {
@@ -831,9 +943,16 @@ export async function runRecommendWorkflow({
       }
       if (detailResult) detailResult.llm_result = llmResult;
     }
-    const screening = useLlmScreening
-      ? llmResultToScreening(llmResult, screeningCandidate)
-      : screenCandidate(screeningCandidate, { criteria });
+    const screening = recoverableDetailError
+      ? createRecoverableDetailFailureScreening(screeningCandidate, recoverableDetailError)
+      : detailResult?.image_evidence?.ok === false
+      ? createImageCaptureFailureScreening(screeningCandidate, {
+        code: detailResult.image_evidence.error_code,
+        message: detailResult.image_evidence.error
+      })
+      : useLlmScreening
+        ? llmResultToScreening(llmResult, screeningCandidate)
+        : screenCandidate(screeningCandidate, { criteria });
     let actionDiscovery = null;
     let postActionResult = null;
     if (postActionEnabled && detailResult) {
@@ -875,6 +994,14 @@ export async function runRecommendWorkflow({
       screening: compactScreening(screening),
       action_discovery: compactActionDiscovery(actionDiscovery),
       post_action: postActionResult,
+      error: recoverableDetailError
+        ? compactRecoverableDetailError(recoverableDetailError)
+        : detailResult?.image_evidence?.ok === false
+        ? compactError({
+          code: detailResult.image_evidence.error_code,
+          message: detailResult.image_evidence.error
+        }, "IMAGE_CAPTURE_FAILED")
+        : null,
       timings
     };
     results.push(compactResult);
@@ -896,6 +1023,9 @@ export async function runRecommendWorkflow({
       llm_screened: results.filter((item) => item.detail?.llm_screening || item.llm_screening).length,
       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,
@@ -920,6 +1050,7 @@ export async function runRecommendWorkflow({
           score: screening.score
         },
         llm_screening: compactScreeningLlmResult(llmResult),
+        error: compactResult.error,
         post_action: postActionResult
       }
     });
@@ -958,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;
@@ -317,6 +377,9 @@ function ensureRecommendRunArtifacts(snapshot) {
       progress: snapshot.progress || {},
       context: snapshot.context || {},
       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()
     });
@@ -395,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
   };
 }
@@ -409,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 || "",
@@ -449,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
   };
@@ -481,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