@reconcrap/boss-recommend-mcp 2.0.29 → 2.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "2.0.29",
+  "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

@@ -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