@reconcrap/boss-recommend-mcp 2.0.20 → 2.0.21

package/package.json

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

package/src/chat-mcp.js

@@ -114,7 +114,8 @@ let chatConnectorImpl = connectChatChromeSession;
 let chatJobReaderImpl = readChatJobOptionsFromSession;
 let chatRunService = createChatRunService({
   idPrefix: "mcp_chat",
-  workflow: (...args) => chatWorkflowImpl(...args)
+  workflow: (...args) => chatWorkflowImpl(...args),
+  onSnapshot: persistChatLifecycleSnapshot
 });
 const chatRunMeta = new Map();
 
@@ -387,6 +388,17 @@ function ensureChatRunArtifacts(snapshot) {
   return artifacts;
 }
 
+function persistChatCheckpointSnapshot(normalized) {
+  const artifacts = getChatRunArtifacts(normalized?.run_id || normalized?.runId);
+  if (!artifacts) return;
+  const checkpoint = normalized?.checkpoint && typeof normalized.checkpoint === "object"
+    ? normalized.checkpoint
+    : {};
+  writeJsonAtomic(artifacts.checkpoint_path, checkpoint);
+  const meta = getChatRunMeta(normalized?.run_id || normalized?.runId);
+  if (meta) meta.checkpointPath = artifacts.checkpoint_path;
+}
+
 function isPidAlive(pid) {
   const numericPid = Number(pid);
   if (!Number.isInteger(numericPid) || numericPid <= 0) return false;
@@ -565,6 +577,7 @@ function buildLegacyChatResult(snapshot) {
 function normalizeRunSnapshot(snapshot) {
   if (!snapshot) return null;
   const meta = getChatRunMeta(snapshot.runId);
+  const artifacts = getChatRunArtifacts(snapshot.runId);
   const summary = snapshot.summary && typeof snapshot.summary === "object" ? snapshot.summary : null;
   const progress = normalizeLegacyProgress(snapshot.progress, summary);
   const legacyResult = (
@@ -606,23 +619,28 @@ function normalizeRunSnapshot(snapshot) {
       cancel_requested: snapshot.status === RUN_STATUS_CANCELING
     },
     resume: {
-      checkpoint_path: legacyResult?.checkpoint_path || null,
-      pause_control_path: getChatRunArtifacts(snapshot.runId)?.run_state_path || null,
+      checkpoint_path: legacyResult?.checkpoint_path || meta.checkpointPath || artifacts?.checkpoint_path || null,
+      pause_control_path: artifacts?.run_state_path || null,
       output_csv: legacyResult?.output_csv || null,
       resume_count: meta.resumeCount || 0,
       last_resumed_at: meta.lastResumedAt || null,
       last_paused_at: snapshot.status === RUN_STATUS_PAUSED ? snapshot.updatedAt : null
     },
     result: legacyResult,
-    artifacts: getChatRunArtifacts(snapshot.runId)
+    artifacts
   };
 }
 
-function persistChatRunSnapshot(snapshot) {
+function persistChatRunSnapshot(snapshot, {
+  persistActiveCheckpoint = false
+} = {}) {
   const normalized = normalizeRunSnapshot(snapshot);
   if (!normalized?.run_id) return normalized;
   const artifacts = getChatRunArtifacts(normalized.run_id);
   if (!artifacts) return normalized;
+  if (persistActiveCheckpoint) {
+    persistChatCheckpointSnapshot(normalized);
+  }
   const payload = {
     run_id: normalized.run_id,
     mode: normalized.mode,
@@ -648,6 +666,12 @@ function persistChatRunSnapshot(snapshot) {
   return normalized;
 }
 
+function persistChatLifecycleSnapshot(snapshot, event = {}) {
+  return persistChatRunSnapshot(snapshot, {
+    persistActiveCheckpoint: event?.type === "checkpoint"
+  });
+}
+
 function attachMethodEvidence(payload, runId) {
   const meta = getChatRunMeta(runId);
   assertNoForbiddenCdpCalls(meta.methodLog || []);
@@ -1729,7 +1753,8 @@ export function __setChatMcpWorkflowForTests(nextWorkflow) {
   chatWorkflowImpl = typeof nextWorkflow === "function" ? nextWorkflow : runChatWorkflow;
   chatRunService = createChatRunService({
     idPrefix: "mcp_chat",
-    workflow: (...args) => chatWorkflowImpl(...args)
+    workflow: (...args) => chatWorkflowImpl(...args),
+    onSnapshot: persistChatLifecycleSnapshot
   });
 }
 

package/src/core/run/index.js

@@ -65,10 +65,24 @@ function snapshotFromEntry(entry) {
 
 export function createRunLifecycleManager({
   idPrefix = "run",
-  now = nowIso
+  now = nowIso,
+  onSnapshot = null
 } = {}) {
   const runs = new Map();
 
+  function emitSnapshot(entry, event = {}) {
+    if (typeof onSnapshot !== "function") return;
+    try {
+      onSnapshot(snapshotFromEntry(entry), {
+        type: event.type || "update",
+        at: now(),
+        ...event
+      });
+    } catch {
+      // Snapshot hooks must never interrupt an active browser run.
+    }
+  }
+
   function getEntry(runId) {
     const entry = runs.get(runId);
     if (!entry) throw new Error(`Unknown runId: ${runId}`);
@@ -83,6 +97,7 @@ export function createRunLifecycleManager({
     entry.run.status = status;
     Object.assign(entry.run, patch);
     touch(entry);
+    emitSnapshot(entry, { type: "status", status });
   }
 
   function createControls(entry) {
@@ -104,6 +119,7 @@ export function createRunLifecycleManager({
           ...progressPatch
         };
         touch(entry);
+        emitSnapshot(entry, { type: "progress", progressPatch });
         return snapshotFromEntry(entry);
       },
       checkpoint(checkpointPatch = {}) {
@@ -113,6 +129,7 @@ export function createRunLifecycleManager({
           updatedAt: now()
         };
         touch(entry);
+        emitSnapshot(entry, { type: "checkpoint", checkpointPatch });
         return snapshotFromEntry(entry);
       },
       async waitIfPaused() {
@@ -231,6 +248,7 @@ export function createRunLifecycleManager({
     entry.pauseRequested = true;
     if (entry.run.status === RUN_STATUS_RUNNING) {
       touch(entry);
+      emitSnapshot(entry, { type: "pause_requested" });
     }
     return snapshotFromEntry(entry);
   }
@@ -246,6 +264,7 @@ export function createRunLifecycleManager({
       setStatus(entry, RUN_STATUS_RUNNING);
     } else {
       touch(entry);
+      emitSnapshot(entry, { type: "resume_requested" });
     }
     return snapshotFromEntry(entry);
   }

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

@@ -1564,9 +1564,10 @@ export async function runChatWorkflow({
 export function createChatRunService({
   lifecycle,
   idPrefix = "chat",
-  workflow = runChatWorkflow
+  workflow = runChatWorkflow,
+  onSnapshot = null
 } = {}) {
-  const manager = lifecycle || createRunLifecycleManager({ idPrefix });
+  const manager = lifecycle || createRunLifecycleManager({ idPrefix, onSnapshot });
 
   function startChatRun({
     client,

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

@@ -957,9 +957,10 @@ export async function runRecommendWorkflow({
 export function createRecommendRunService({
   lifecycle,
   idPrefix = "recommend",
-  workflow = runRecommendWorkflow
+  workflow = runRecommendWorkflow,
+  onSnapshot = null
 } = {}) {
-  const manager = lifecycle || createRunLifecycleManager({ idPrefix });
+  const manager = lifecycle || createRunLifecycleManager({ idPrefix, onSnapshot });
 
   function startRecommendRun({
     client,

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

@@ -619,9 +619,10 @@ export async function runRecruitWorkflow({
 export function createRecruitRunService({
   lifecycle,
   idPrefix = "recruit",
-  workflow = runRecruitWorkflow
+  workflow = runRecruitWorkflow,
+  onSnapshot = null
 } = {}) {
-  const manager = lifecycle || createRunLifecycleManager({ idPrefix });
+  const manager = lifecycle || createRunLifecycleManager({ idPrefix, onSnapshot });
 
   function startRecruitRun({
     client,

package/src/recommend-mcp.js

@@ -52,7 +52,7 @@ import {
 const DEFAULT_RECOMMEND_HOST = "127.0.0.1";
 const DEFAULT_RECOMMEND_PORT = 9222;
 const DEFAULT_RECOMMEND_POLL_AFTER_SEC = 10;
-const TARGET_COUNT_SEMANTICS = "target_count means processed recommend candidates, not passed candidates";
+const TARGET_COUNT_SEMANTICS = "target_count means candidates that pass screening; scan continues until that many candidates pass or the list ends";
 const RUN_MODE_ASYNC = "async";
 
 const TERMINAL_STATUSES = new Set([
@@ -66,7 +66,8 @@ let recommendConnectorImpl = connectRecommendChromeSession;
 let recommendJobReaderImpl = readRecommendJobOptionsFromSession;
 let recommendRunService = createRecommendRunService({
   idPrefix: "mcp_recommend",
-  workflow: (...args) => recommendWorkflowImpl(...args)
+  workflow: (...args) => recommendWorkflowImpl(...args),
+  onSnapshot: persistRecommendLifecycleSnapshot
 });
 const recommendRunMeta = new Map();
 
@@ -328,6 +329,17 @@ function ensureRecommendRunArtifacts(snapshot) {
   return artifacts;
 }
 
+function persistRecommendCheckpointSnapshot(normalized) {
+  const artifacts = getRecommendRunArtifacts(normalized?.run_id || normalized?.runId);
+  if (!artifacts) return;
+  const checkpoint = normalized?.checkpoint && typeof normalized.checkpoint === "object"
+    ? normalized.checkpoint
+    : {};
+  writeJsonAtomic(artifacts.checkpoint_path, checkpoint);
+  const meta = getRecommendRunMeta(normalized?.run_id || normalized?.runId);
+  if (meta) meta.checkpointPath = artifacts.checkpoint_path;
+}
+
 function buildLegacyRecommendResult(snapshot) {
   if (!snapshot) return null;
   const artifacts = ensureRecommendRunArtifacts(snapshot);
@@ -390,6 +402,7 @@ function buildLegacyRecommendResult(snapshot) {
 function normalizeRunSnapshot(snapshot) {
   if (!snapshot) return null;
   const meta = getRecommendRunMeta(snapshot.runId);
+  const artifacts = getRecommendRunArtifacts(snapshot.runId);
   const summary = snapshot.summary && typeof snapshot.summary === "object" ? snapshot.summary : null;
   const progress = normalizeLegacyProgress(snapshot.progress, summary);
   const legacyResult = (
@@ -429,23 +442,28 @@ function normalizeRunSnapshot(snapshot) {
       cancel_requested: snapshot.status === RUN_STATUS_CANCELING
     },
     resume: {
-      checkpoint_path: legacyResult?.checkpoint_path || null,
-      pause_control_path: getRecommendRunArtifacts(snapshot.runId)?.run_state_path || null,
+      checkpoint_path: legacyResult?.checkpoint_path || meta.checkpointPath || artifacts?.checkpoint_path || null,
+      pause_control_path: artifacts?.run_state_path || null,
       output_csv: legacyResult?.output_csv || null,
       resume_count: meta.resumeCount || 0,
       last_resumed_at: meta.lastResumedAt || null,
       last_paused_at: snapshot.status === RUN_STATUS_PAUSED ? snapshot.updatedAt : null
     },
     result: legacyResult,
-    artifacts: getRecommendRunArtifacts(snapshot.runId)
+    artifacts
   };
 }
 
-function persistRecommendRunSnapshot(snapshot) {
+function persistRecommendRunSnapshot(snapshot, {
+  persistActiveCheckpoint = false
+} = {}) {
   const normalized = normalizeRunSnapshot(snapshot);
   if (!normalized?.run_id) return normalized;
   const artifacts = getRecommendRunArtifacts(normalized.run_id);
   if (!artifacts) return normalized;
+  if (persistActiveCheckpoint) {
+    persistRecommendCheckpointSnapshot(normalized);
+  }
   const payload = {
     run_id: normalized.run_id,
     mode: normalized.mode,
@@ -471,6 +489,12 @@ function persistRecommendRunSnapshot(snapshot) {
   return normalized;
 }
 
+function persistRecommendLifecycleSnapshot(snapshot, event = {}) {
+  return persistRecommendRunSnapshot(snapshot, {
+    persistActiveCheckpoint: event?.type === "checkpoint"
+  });
+}
+
 function attachMethodEvidence(payload, runId) {
   const meta = getRecommendRunMeta(runId);
   assertNoForbiddenCdpCalls(meta.methodLog || []);
@@ -1440,7 +1464,8 @@ export function __setRecommendMcpWorkflowForTests(nextWorkflow) {
   recommendWorkflowImpl = typeof nextWorkflow === "function" ? nextWorkflow : runRecommendWorkflow;
   recommendRunService = createRecommendRunService({
     idPrefix: "mcp_recommend",
-    workflow: (...args) => recommendWorkflowImpl(...args)
+    workflow: (...args) => recommendWorkflowImpl(...args),
+    onSnapshot: persistRecommendLifecycleSnapshot
   });
 }
 

package/src/recruit-mcp.js

@@ -42,7 +42,7 @@ const RUN_MODE_SYNC = "sync";
 const DEFAULT_RECRUIT_POLL_AFTER_SEC = 10;
 const DEFAULT_RECRUIT_HOST = "127.0.0.1";
 const DEFAULT_RECRUIT_PORT = 9222;
-const TARGET_COUNT_SEMANTICS = "target_count means processed candidate count, not passed candidate count";
+const TARGET_COUNT_SEMANTICS = "target_count means candidates that pass screening; scan continues until that many candidates pass or the list ends";
 const DEFAULT_RECRUIT_HOME_DIR = ".boss-recruit-mcp";
 
 const TERMINAL_STATUSES = new Set([
@@ -55,7 +55,8 @@ let recruitWorkflowImpl = runRecruitWorkflow;
 let recruitConnectorImpl = connectRecruitChromeSession;
 let recruitRunService = createRecruitRunService({
   idPrefix: "mcp_recruit",
-  workflow: (...args) => recruitWorkflowImpl(...args)
+  workflow: (...args) => recruitWorkflowImpl(...args),
+  onSnapshot: persistRecruitLifecycleSnapshot
 });
 const recruitRunMeta = new Map();
 
@@ -253,6 +254,17 @@ function ensureRecruitRunArtifacts(snapshot) {
   return artifacts;
 }
 
+function persistRecruitCheckpointSnapshot(normalized) {
+  const artifacts = getRecruitRunArtifacts(normalized?.run_id || normalized?.runId);
+  if (!artifacts) return;
+  const checkpoint = normalized?.checkpoint && typeof normalized.checkpoint === "object"
+    ? normalized.checkpoint
+    : {};
+  writeJsonAtomic(artifacts.checkpoint_path, checkpoint);
+  const meta = getRecruitRunMeta(normalized?.run_id || normalized?.runId);
+  if (meta) meta.checkpointPath = artifacts.checkpoint_path;
+}
+
 function toIsoOrNull(value) {
   const normalized = normalizeText(value);
   return normalized || null;
@@ -565,6 +577,7 @@ function evaluateRecruitPipelineGate(parsed) {
 function normalizeRunSnapshot(snapshot) {
   if (!snapshot) return null;
   const meta = getRecruitRunMeta(snapshot.runId);
+  const artifacts = getRecruitRunArtifacts(snapshot.runId);
   const summary = snapshot.summary && typeof snapshot.summary === "object" ? snapshot.summary : null;
   const progress = normalizeLegacyProgress(snapshot.progress, summary);
   const legacyResult = (
@@ -603,27 +616,33 @@ function normalizeRunSnapshot(snapshot) {
       cancel_requested: snapshot.status === RUN_STATUS_CANCELING
     },
     resume: {
-      checkpoint_path: legacyResult?.checkpoint_path || null,
-      pause_control_path: getRecruitRunArtifacts(snapshot.runId)?.run_state_path || null,
+      checkpoint_path: legacyResult?.checkpoint_path || meta.checkpointPath || artifacts?.checkpoint_path || null,
+      pause_control_path: artifacts?.run_state_path || null,
       output_csv: legacyResult?.output_csv || null,
       resume_count: meta.resumeCount || 0,
       last_resumed_at: meta.lastResumedAt || null,
       last_paused_at: snapshot.status === RUN_STATUS_PAUSED ? snapshot.updatedAt : null
     },
     result: legacyResult,
-    artifacts: getRecruitRunArtifacts(snapshot.runId)
+    artifacts
   };
 }
 
-function persistRecruitRunSnapshot(snapshot) {
+function persistRecruitRunSnapshot(snapshot, {
+  persistActiveCheckpoint = false
+} = {}) {
   const normalized = normalizeRunSnapshot(snapshot);
   if (!normalized?.run_id) return normalized;
   const artifacts = getRecruitRunArtifacts(normalized.run_id);
   if (!artifacts) return normalized;
+  if (persistActiveCheckpoint) {
+    persistRecruitCheckpointSnapshot(normalized);
+  }
   const payload = {
     run_id: normalized.run_id,
     mode: normalized.mode,
     state: normalized.state,
+    status: normalized.status,
     stage: normalized.stage,
     started_at: normalized.started_at,
     updated_at: normalized.updated_at,
@@ -644,6 +663,12 @@ function persistRecruitRunSnapshot(snapshot) {
   return normalized;
 }
 
+function persistRecruitLifecycleSnapshot(snapshot, event = {}) {
+  return persistRecruitRunSnapshot(snapshot, {
+    persistActiveCheckpoint: event?.type === "checkpoint"
+  });
+}
+
 function getRecruitRunMeta(runId) {
   return recruitRunMeta.get(runId) || {};
 }
@@ -1248,7 +1273,8 @@ export function __setRecruitMcpWorkflowForTests(nextWorkflow) {
   recruitWorkflowImpl = typeof nextWorkflow === "function" ? nextWorkflow : runRecruitWorkflow;
   recruitRunService = createRecruitRunService({
     idPrefix: "mcp_recruit",
-    workflow: (...args) => recruitWorkflowImpl(...args)
+    workflow: (...args) => recruitWorkflowImpl(...args),
+    onSnapshot: persistRecruitLifecycleSnapshot
   });
 }