neoagent 3.2.1-beta.8 → 3.2.1-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neoagent",
-  "version": "3.2.1-beta.8",
+  "version": "3.2.1-beta.9",
   "description": "Self-hosted AI agent for long-running tasks, automation, messaging, device control, and local memory",
   "license": "AGPL-3.0-only",
   "main": "server/index.js",

package/server/public/.last_build_id

@@ -1 +1 @@
-38fc05bea2f5bf14dda4c0f58b31ff9a
+1a325740c55a320441979a83b65c758d

package/server/public/flutter_bootstrap.js

@@ -37,6 +37,6 @@ _flutter.buildConfig = {"engineRevision":"0cd610717bde95fd88343c64f81c11ba4e5c00
 
 _flutter.loader.load({
   serviceWorkerSettings: {
-    serviceWorkerVersion: "222530411" /* Flutter's service worker is deprecated and will be removed in a future Flutter release. */
+    serviceWorkerVersion: "393614478" /* Flutter's service worker is deprecated and will be removed in a future Flutter release. */
   }
 });

package/server/public/main.dart.js

@@ -144506,7 +144506,7 @@ if(r){r=s.d
 r===$&&A.b()
 p.push(A.ju(q,A.jx(!1,new A.Y(B.wP,A.cU(new A.cH(B.kE,new A.acU(r,q),q),q,q),q),!1,B.J,!0),q,q,0,0,0,q))}if(!s.ay){r=s.e
 r===$&&A.b()
-r=B.b.t("mryrwx0x-27df61b").length!==0&&r.b}else r=!1
+r=B.b.t("ms0ggj2e-2c398a2").length!==0&&r.b}else r=!1
 if(r){r=s.d
 r===$&&A.b()
 r=r.aU&&!r.ag?84:0
@@ -150393,7 +150393,7 @@ $S:0}
 A.a3j.prototype={}
 A.WC.prototype={
 r9(a){var s=this
-if(B.b.t("mryrwx0x-27df61b").length===0||s.a!=null)return
+if(B.b.t("ms0ggj2e-2c398a2").length===0||s.a!=null)return
 s.Co()
 s.a=A.mL(B.Yh,new A.bmK(s))},
 Co(){var s=0,r=A.l(t.H),q,p=2,o=[],n=this,m,l,k,j,i,h,g,f
@@ -150411,7 +150411,7 @@ if(!t.f.b(k)){s=1
 break}i=J.a0(k,"buildId")
 h=i==null?null:B.b.t(J.q(i))
 j=h==null?"":h
-if(J.bv(j)===0||J.e(j,"mryrwx0x-27df61b")){s=1
+if(J.bv(j)===0||J.e(j,"ms0ggj2e-2c398a2")){s=1
 break}n.b=!0
 n.H()
 p=2
@@ -150428,7 +150428,7 @@ case 2:return A.i(o.at(-1),r)}})
 return A.k($async$Co,r)},
 wV(){var s=0,r=A.l(t.H),q,p=2,o=[],n=this,m,l,k,j,i,h,g,f,e,d,c,b,a,a0,a1
 var $async$wV=A.h(function(a2,a3){if(a2===1){o.push(a3)
-s=p}for(;;)switch(s){case 0:if(B.b.t("mryrwx0x-27df61b").length===0||n.c){s=1
+s=p}for(;;)switch(s){case 0:if(B.b.t("ms0ggj2e-2c398a2").length===0||n.c){s=1
 break}n.c=!0
 n.H()
 p=4

package/server/services/ai/loop/agent_engine_core.js

@@ -87,6 +87,7 @@ const {
 } = require('../messagingFallback');
 const { isDeferredWorkReply } = require('../terminal_reply');
 const {
+  assessResearchAdequacy,
   summarizeToolExecutions,
 } = require('../toolEvidence');
 const {
@@ -793,6 +794,11 @@ class AgentEngine {
   }) {
     const runMeta = options?.runId ? this.getRunMeta(options.runId) : null;
     const goalContext = resolveRunGoalContext(runMeta, analysis, plan);
+    const researchAdequacy = assessResearchAdequacy({
+      analysis,
+      goalContext,
+      toolExecutions,
+    });
     const response = await this.requestStructuredJson({
       provider,
       providerName,
@@ -808,6 +814,8 @@ class AgentEngine {
         lastReply,
         iteration,
         maxIterations,
+        analysis,
+        researchAdequacy,
       }),
       maxTokens: 500,
       normalize: (raw) => normalizeCompletionDecision(raw, 'continue'),
@@ -817,9 +825,15 @@ class AgentEngine {
       phase: 'completion_decision',
     });
     return {
-      decision: enforceTerminalReplyDecision(response.value, lastReply),
+      decision: enforceTerminalReplyDecision(response.value, lastReply, {
+        analysis,
+        goalContext,
+        toolExecutions,
+        researchAdequacy,
+      }),
       usage: response.usage,
       raw: response.raw,
+      researchAdequacy,
     };
   }
 
@@ -905,6 +919,12 @@ class AgentEngine {
         goalContext,
         toolExecutions,
         iteration,
+        analysis,
+        researchAdequacy: assessResearchAdequacy({
+          analysis,
+          goalContext,
+          toolExecutions,
+        }),
       }),
       maxTokens: 200,
       normalize: normalizeChurnAssessment,

package/server/services/ai/loop/completion_judge.js

@@ -7,6 +7,8 @@ const {
   isTerminalQuestionOrBlockerReply,
 } = require('../terminal_reply');
 const {
+  assessResearchAdequacy,
+  formatResearchAdequacyGuidance,
   summarizeAvailableTools,
   summarizeToolExecutions,
 } = require('../toolEvidence');
@@ -198,8 +200,15 @@ function buildCompletionDecisionPrompt({
   lastReply,
   iteration,
   maxIterations,
+  analysis = null,
+  researchAdequacy = null,
 }) {
   const draftReply = normalizeOutgoingMessage(lastReply) || '';
+  const adequacy = researchAdequacy || assessResearchAdequacy({
+    analysis,
+    goalContext,
+    toolExecutions,
+  });
   const lines = [
     'Return JSON only.',
     'Decide whether this run should continue autonomously or stop now.',
@@ -214,13 +223,29 @@ function buildCompletionDecisionPrompt({
     '- A tool-specific API error, timeout, rate limit, or missing result inside this run is usually "continue", not "blocked", if any other available tool could still make progress.',
     '- Repeated read-only inspection that has already established the relevant object is absent or unchanged is not progress. Accept a concise complete/blocker reply instead of requiring more searching.',
     `- If completion_confidence_required is ${goalContext.effectiveCompletionConfidence} and the latest draft depends on unverified assumptions, use "continue" so the run can gather evidence, inspect state, or narrow the reply.`,
-    triggerSource === 'messaging' && messagingSent
-      ? '- A final reply was already delivered via send_message. Use "complete" unless concrete task work remains.'
-      : triggerSource === 'messaging'
-        ? '- For messaging, do not stop on a partial status message. Continue unless the task is actually complete or externally blocked.'
-        : '- Do not stop just because you wrote a status update. Continue unless the task is actually complete or externally blocked.',
+    '- When research intensity is light or deep, use "continue" until the required primary/source coverage and target coverage are met, or the draft is an explicit blocker naming exactly what could not be verified.',
+    '- Search snippets, memory, and model priors are leads, not completion evidence. Prefer opened/fetched primary sources before "complete".',
   ];
 
+  if (adequacy.intensity !== 'none') {
+    lines.push(
+      `- Research intensity for this run is ${adequacy.intensity}. Current coverage: primary=${adequacy.primarySourceCount}/${adequacy.requiredPrimarySources}, secondary=${adequacy.secondarySourceCount}, targets_covered=${adequacy.coveredTargets.length}/${Math.max(adequacy.requiredTargetCoverage, adequacy.targets.length)}.`,
+    );
+  }
+  if (adequacy.adequate === false) {
+    lines.push(
+      `- Research is still incomplete (${adequacy.reason}). Use "continue" unless the latest draft is an explicit blocker naming the exact missing evidence.`,
+    );
+  }
+
+  if (triggerSource === 'messaging' && messagingSent) {
+    lines.push('- A final reply was already delivered via send_message. Use "complete" unless concrete task work remains.');
+  } else if (triggerSource === 'messaging') {
+    lines.push('- For messaging, do not stop on a partial status message. Continue unless the task is actually complete or externally blocked.');
+  } else {
+    lines.push('- Do not stop just because you wrote a status update. Continue unless the task is actually complete or externally blocked.');
+  }
+
   lines.push(
     goalContext.effectiveGoal ? `Goal: ${goalContext.effectiveGoal}` : '',
     goalContext.persistedGoalPrompt,
@@ -231,6 +256,16 @@ function buildCompletionDecisionPrompt({
     `Current iteration: ${iteration} of ${maxIterations}.`,
     `Available tools in this run: ${summarizeAvailableTools(tools) || 'none'}`,
     `Recent tool evidence:\n${summarizeToolExecutions(toolExecutions, 8) || 'none'}`,
+    adequacy.intensity !== 'none'
+      ? `Research adequacy: intensity=${adequacy.intensity}; adequate=${adequacy.adequate}; reason=${adequacy.reason}`
+      : '',
+    adequacy.targets.length
+      ? `Research targets: ${adequacy.targets.join('; ')}`
+      : '',
+    adequacy.uncoveredTargets.length
+      ? `Uncovered research targets: ${adequacy.uncoveredTargets.join('; ')}`
+      : '',
+    formatResearchAdequacyGuidance(adequacy),
     `Latest draft reply:\n${draftReply || '(empty)'}`,
   );
   return lines.filter(Boolean).join('\n');
@@ -245,7 +280,7 @@ function normalizeCompletionDecision(raw, fallbackStatus = 'continue') {
   };
 }
 
-function enforceTerminalReplyDecision(decision, lastReply) {
+function enforceTerminalReplyDecision(decision, lastReply, options = {}) {
   if (isDeferredWorkReply(lastReply)) {
     return {
       status: 'continue',
@@ -258,6 +293,25 @@ function enforceTerminalReplyDecision(decision, lastReply) {
       reason: 'The latest reply asks for user input or states a concrete blocker, so the run must wait instead of repeating it.',
     };
   }
+
+  const researchAdequacy = options.researchAdequacy
+    || assessResearchAdequacy({
+      analysis: options.analysis || null,
+      goalContext: options.goalContext || null,
+      toolExecutions: options.toolExecutions || [],
+    });
+  if (
+    researchAdequacy
+    && researchAdequacy.adequate === false
+    && (decision?.status === 'complete' || decision?.status === 'blocked')
+    && !isTerminalQuestionOrBlockerReply(lastReply)
+  ) {
+    return {
+      status: 'continue',
+      reason: researchAdequacy.reason
+        || 'Research evidence is still incomplete for the requested targets; continue gathering sources before finishing.',
+    };
+  }
   return decision;
 }
 
@@ -269,7 +323,14 @@ function buildChurnAssessmentPrompt({
   goalContext,
   toolExecutions,
   iteration,
+  analysis = null,
+  researchAdequacy = null,
 }) {
+  const adequacy = researchAdequacy || assessResearchAdequacy({
+    analysis,
+    goalContext,
+    toolExecutions,
+  });
   const lines = [
     'Return JSON only.',
     'Self-assess your current loop state — are you making genuine progress or spinning?',
@@ -283,11 +344,19 @@ function buildChurnAssessmentPrompt({
       : '',
     `Iteration: ${iteration}`,
     `Recent tool evidence:\n${summarizeToolExecutions(toolExecutions, 6) || 'none'}`,
+    adequacy.intensity !== 'none'
+      ? `Research adequacy: intensity=${adequacy.intensity}; adequate=${adequacy.adequate}; covered=${adequacy.coveredTargets.length}/${Math.max(adequacy.requiredTargetCoverage, adequacy.targets.length)}; primary=${adequacy.primarySourceCount}/${adequacy.requiredPrimarySources}.`
+      : '',
+    adequacy.uncoveredTargets.length
+      ? `Still uncovered research targets: ${adequacy.uncoveredTargets.join('; ')}.`
+      : '',
     '',
     'Assessment rules:',
     '- "progressing": You are systematically gathering necessary context and the next concrete action is already determined — you know exactly what to do next.',
     '- "churn": You are re-reading/re-searching information already in context, or exploring without a clear next concrete step. Accept the nudge and act.',
     '- "blocked": No concrete action is available in this run. You have all the evidence needed to deliver a truthful final answer or a specific external blocker.',
+    '- For multi-target research, keep "progressing" while uncovered targets remain and a fresh primary source can still be opened. Do not mark "blocked" just because you have partial notes.',
+    '- Re-querying the same snippet source for an already covered target is "churn". Opening a different primary source for an uncovered target is "progressing".',
   ];
   return lines.filter(Boolean).join('\n');
 }

package/server/services/ai/taskAnalysis.js

@@ -24,6 +24,7 @@ const ANALYSIS_SCHEMA_EXAMPLE = {
   draft_reply: '',
   goal: 'Answer the user accurately.',
   success_criteria: ['Final reply is correct and specific.'],
+  research_targets: [],
   suggested_tools: ['web_search', 'browser_navigate'],
   complexity: 'standard',
   autonomy_level: 'normal',
@@ -59,6 +60,8 @@ const ANALYSIS_PROMPT_INSTRUCTIONS = [
   'Do not suggest create_task, update_task, delete_task, or list_tasks for ordinary immediate work. Use task tools only when the user asks for future, recurring, scheduled, monitored, background, or existing-task management behavior.',
   'Set parallel_work=true when independent tool calls or subagents can materially reduce latency.',
   'Set completion_confidence_required="high" when wrong completion would be costly, state-changing, user-visible, or hard to recover.',
+  'For research, product/device comparisons, reviews, fact-checks, or multi-entity look-into requests, use mode="execute" or mode="plan_execute", never direct_answer. Set needs_verification=true, freshness_risk="possible" or higher, and completion_confidence_required="high".',
+  'When the user asks to look into multiple devices, products, options, or entities, put each named target into research_targets and success_criteria and keep them exact. Prefer suggested_tools that can open primary sources (web_search plus browser_navigate/http_request) rather than answering from memory.',
 ];
 const PLAN_PROMPT_INSTRUCTIONS = [
   'Create a concise execution plan for the current task.',
@@ -83,9 +86,12 @@ const VERIFIER_PROMPT_INSTRUCTIONS = [
   'A successful create_task or update_task tool call is required before claiming a task schedule changed.',
   'If external evidence conflicts with memory, history, or another tool result, preserve the uncertainty instead of flattening it into a single confident claim.',
   'When the draft reply is already correct and fully supported by the evidence, return it unchanged. Do not rewrite for style.',
+  'For multi-entity research or comparison replies, every compared target needs supporting tool evidence. If a target was never searched or opened, mark insufficient_evidence and rewrite the reply so it does not invent that target\'s specs.',
+  'Search-result snippets alone are weak evidence for concrete product claims. Prefer opened pages, fetched docs, or other primary tool output. If only snippets exist, either keep the claim clearly provisional or mark missing_evidence.',
 ];
 const EXECUTION_GUIDANCE_ACTION_LINES = [
   'Act end-to-end. Run independent searches or inspections in parallel when possible. Prefer native integration tools and structured APIs over browser automation or shell scraping. Use exact IDs and required parameters; list or search first when you do not have them.',
+  'For research and multi-entity comparisons, cover each requested target with its own search/open path. Do not stop after one partial lead or invent the remaining devices from memory. Open primary sources before stating concrete specs.',
   'For GitHub issue implementation or PR work, fetch the issue once, then establish or reuse a writable local checkout, create a task branch, inspect/edit/test locally, and push/open the PR. Use direct GitHub file mutation tools only as a fallback when a local checkout is unavailable.',
   'Prefer the highest-level available tool for the job. If a tool accepts normal text, JSON, file paths, or line ranges, pass those directly instead of reconstructing equivalent data through shell commands.',
   'Your shell (execute_command) starts in your workspace, and the file tools (read_file, read_files, write_file, edit_file, replace_file_range, list_directory, search_files) operate on that same workspace. Keep source checkouts and generated files in the shared workspace, then prefer file tools for inspection and edits instead of shell snippets. Clone a repo once and reuse it; do not re-clone or re-list the same tree.',
@@ -317,6 +323,13 @@ function normalizeTaskAnalysis(raw = {}, fallback = {}) {
     'successCriteria',
     TASK_ANALYSIS_SUCCESS_CRITERIA_LIMIT,
   );
+  const researchTargets = resolveAliasedStringList(
+    raw,
+    fallback,
+    'research_targets',
+    'researchTargets',
+    TASK_ANALYSIS_SUCCESS_CRITERIA_LIMIT,
+  );
 
   const draftReply = resolveAliasedText(raw, fallback, 'draft_reply', 'draftReply', '');
   const initialMode = pickEnum(
@@ -398,6 +411,7 @@ function normalizeTaskAnalysis(raw = {}, fallback = {}) {
     draft_reply: draftReply,
     goal: resolveAliasedText(raw, fallback, 'goal', 'goal', ''),
     success_criteria: successCriteria,
+    research_targets: researchTargets,
     complexity: mode === 'plan_execute' ? 'complex' : normalizedComplexity,
     autonomy_level: mode === 'plan_execute' ? 'high' : normalizedAutonomyLevel,
     progress_update_policy: pickEnum(
@@ -567,6 +581,7 @@ function buildExecutionGuidance({ analysis, plan = null, capabilityHealth }) {
     `Execution mode: ${analysis.mode}.`,
     analysis.goal ? `Goal: ${analysis.goal}` : '',
     formatBulletSection('Success criteria', analysis.success_criteria),
+    formatBulletSection('Research targets', analysis.research_targets),
     analysis.suggested_tools?.length
       ? `Advisory tool suggestions: ${analysis.suggested_tools.join(', ')}`
       : '',

package/server/services/ai/toolEvidence.js

@@ -200,6 +200,356 @@ function isSubstantiveProgressToolName(toolName = '') {
   return true;
 }
 
+const PRIMARY_RESEARCH_SOURCES = new Set([
+  'browser',
+  'http',
+  'integration',
+  'files',
+  'command',
+  'mcp',
+  'android',
+  'data',
+  'vision',
+  'skills',
+  'subagent',
+]);
+
+const SECONDARY_RESEARCH_SOURCES = new Set([
+  'search',
+  'memory',
+]);
+
+// External/source-backed tools only. Local file/edit/shell work must not
+// inherit a research burden just because inspection tools are available.
+const RESEARCH_TOOL_HINTS = new Set([
+  'web_search',
+  'http_request',
+  'browser_navigate',
+  'browser_open',
+  'browser_click',
+  'browser_type',
+  'browser_snapshot',
+  'browser_evaluate',
+  'analyze_image',
+  'spawn_subagent',
+  'delegate_to_agent',
+]);
+
+function clampResearchText(value, maxChars = 220) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (!text) return '';
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+
+function uniqueResearchTokens(values = [], { limit = 12 } = {}) {
+  const seen = new Set();
+  const tokens = [];
+  for (const value of values) {
+    const token = String(value || '').replace(/\s+/g, ' ').trim();
+    if (!token) continue;
+    const key = token.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    tokens.push(token);
+    if (tokens.length >= limit) break;
+  }
+  return tokens;
+}
+
+// Structural target extraction only: quoted spans and product-like proper names.
+// No phrase-based intent filters.
+function isProductLikeToken(token = '') {
+  const value = String(token || '').trim();
+  if (!value) return false;
+  if (/[0-9]/.test(value)) return true;
+  if (/[-_/]/.test(value)) return true;
+  if (/[a-z][A-Z]/.test(value)) return true;
+  return false;
+}
+
+function extractResearchTargets(text = '') {
+  const raw = String(text || '');
+  if (!raw.trim()) return [];
+
+  const targets = [];
+  const quoted = raw.match(/["“”'‘’`]([^"“”'‘’`]{2,80})["“”'‘’`]/g) || [];
+  for (const match of quoted) {
+    const cleaned = match.replace(/^["“”'‘’`]|["“”'‘’`]$/g, '').trim();
+    if (cleaned) targets.push(cleaned);
+  }
+
+  // Require each subsequent token to start with a capital letter or digit so
+  // ordinary sentence fragments ("Implement the pause...") do not become targets.
+  const productish = raw.match(
+    /\b[A-Z][A-Za-z0-9+./-]*(?:[ -][A-Z0-9][A-Za-z0-9+./-]*){0,5}\b/g,
+  ) || [];
+  for (const match of productish) {
+    const cleaned = match.replace(/\s+/g, ' ').trim();
+    const parts = cleaned.split(/\s+/).filter(Boolean);
+    if (parts.length === 0) continue;
+    if (parts.length === 1) {
+      if (!isProductLikeToken(parts[0]) || parts[0].length < 4) continue;
+    } else if (!parts.some(isProductLikeToken) && parts.length < 2) {
+      continue;
+    } else if (!parts.some(isProductLikeToken) && parts.every((part) => part.length <= 3)) {
+      continue;
+    }
+    // Drop pure sentence openers with no product-like signal.
+    if (parts.length >= 2 && !parts.some(isProductLikeToken)) {
+      // Keep multi-token proper names such as brand + model family only when
+      // at least one token is long enough to be a meaningful entity name.
+      if (!parts.some((part) => part.length >= 5)) continue;
+    }
+    targets.push(cleaned);
+  }
+
+  return uniqueResearchTokens(targets, { limit: 8 });
+}
+
+function collectResearchTargets(analysis = null, goalContext = null) {
+  const explicit = uniqueResearchTokens([
+    ...(Array.isArray(analysis?.research_targets) ? analysis.research_targets : []),
+    ...(Array.isArray(goalContext?.researchTargets) ? goalContext.researchTargets : []),
+  ], { limit: 8 });
+  if (explicit.length > 0) return explicit;
+
+  const goalText = [
+    goalContext?.effectiveGoal,
+    analysis?.goal,
+    ...(Array.isArray(goalContext?.successCriteria) ? goalContext.successCriteria : []),
+    ...(Array.isArray(analysis?.success_criteria) ? analysis.success_criteria : []),
+  ].filter(Boolean).join(' ');
+
+  return extractResearchTargets(goalText);
+}
+
+function hasResearchToolHint(analysis = null) {
+  const tools = Array.isArray(analysis?.suggested_tools) ? analysis.suggested_tools : [];
+  return tools.some((name) => {
+    const tool = String(name || '').trim().toLowerCase();
+    if (!tool) return false;
+    if (RESEARCH_TOOL_HINTS.has(tool)) return true;
+    return tool.startsWith('browser_')
+      || tool.startsWith('mcp_')
+      || tool === 'web_search'
+      || tool.includes('web_search')
+      || tool.includes('http_request');
+  });
+}
+
+function resolveResearchIntensity(analysis = null, goalContext = null) {
+  const mode = String(analysis?.mode || '').trim().toLowerCase();
+  const complexity = String(
+    goalContext?.effectiveComplexity
+    || analysis?.complexity
+    || '',
+  ).trim().toLowerCase();
+  const autonomyLevel = String(
+    goalContext?.effectiveAutonomyLevel
+    || analysis?.autonomy_level
+    || '',
+  ).trim().toLowerCase();
+  const completionConfidence = String(
+    goalContext?.effectiveCompletionConfidence
+    || analysis?.completion_confidence_required
+    || '',
+  ).trim().toLowerCase();
+  const verificationNeed = String(analysis?.verification_need || '').trim().toLowerCase();
+  const freshnessRisk = String(analysis?.freshness_risk || '').trim().toLowerCase();
+  const planningDepth = String(analysis?.planning_depth || '').trim().toLowerCase();
+  const targets = collectResearchTargets(analysis, goalContext);
+  const researchToolHint = hasResearchToolHint(analysis);
+
+  if (mode === 'direct_answer' && verificationNeed === 'none' && freshnessRisk === 'none') {
+    return 'none';
+  }
+
+  // External/source-backed work only. Pure local implementation tasks must not
+  // inherit a research burden just because they are complex or multi-step.
+  const needsExternalEvidence = (
+    targets.length > 0
+    || researchToolHint
+    || freshnessRisk === 'possible'
+    || freshnessRisk === 'high'
+    || verificationNeed === 'required'
+  );
+  if (!needsExternalEvidence) {
+    return 'none';
+  }
+
+  const deepSignals = [
+    mode === 'plan_execute',
+    complexity === 'complex',
+    autonomyLevel === 'high',
+    completionConfidence === 'high',
+    verificationNeed === 'required',
+    freshnessRisk === 'high',
+    planningDepth === 'deep',
+    targets.length >= 2,
+  ].filter(Boolean).length;
+
+  if (deepSignals >= 2 || targets.length >= 2 || verificationNeed === 'required' || freshnessRisk === 'high') {
+    return 'deep';
+  }
+
+  return 'light';
+}
+
+function isSuccessfulResearchExecution(item = {}) {
+  if (!item || item.ok !== true) return false;
+  if (!isSubstantiveProgressToolName(item.toolName)) return false;
+  if (item.evidenceSource === 'messaging') return false;
+  return Boolean(item.evidenceRelevant || item.dependsOnOutput || item.stateChanged);
+}
+
+function isPrimaryResearchSource(source = '') {
+  return PRIMARY_RESEARCH_SOURCES.has(String(source || '').trim().toLowerCase());
+}
+
+function isSecondaryResearchSource(source = '') {
+  return SECONDARY_RESEARCH_SOURCES.has(String(source || '').trim().toLowerCase());
+}
+
+function executionMentionsTarget(execution = {}, target = '') {
+  const needle = String(target || '').trim().toLowerCase();
+  if (!needle) return false;
+  const haystack = [
+    execution.summary,
+    execution.toolName,
+    execution.evidenceSource,
+    JSON.stringify(execution.input || {}),
+  ].join(' ').toLowerCase();
+  if (haystack.includes(needle)) return true;
+
+  const tokens = needle
+    .split(/[^a-z0-9+]+/i)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 3);
+  if (tokens.length === 0) return false;
+  const matched = tokens.filter((token) => haystack.includes(token)).length;
+  return matched >= Math.min(2, tokens.length);
+}
+
+function assessResearchAdequacy({
+  analysis = null,
+  goalContext = null,
+  toolExecutions = [],
+} = {}) {
+  const intensity = resolveResearchIntensity(analysis, goalContext);
+  const targets = collectResearchTargets(analysis, goalContext);
+
+  const successful = (Array.isArray(toolExecutions) ? toolExecutions : [])
+    .filter(isSuccessfulResearchExecution);
+  const primary = successful.filter((item) => isPrimaryResearchSource(item.evidenceSource));
+  const secondary = successful.filter((item) => isSecondaryResearchSource(item.evidenceSource));
+  const coveredTargets = targets.filter((target) => (
+    successful.some((item) => executionMentionsTarget(item, target))
+  ));
+  const primaryCoveredTargets = targets.filter((target) => (
+    primary.some((item) => executionMentionsTarget(item, target))
+  ));
+  const uncoveredTargets = targets.filter((target) => !coveredTargets.includes(target));
+  const primaryUncoveredTargets = targets.filter((target) => !primaryCoveredTargets.includes(target));
+
+  const requiredPrimarySources = intensity === 'deep'
+    ? (targets.length > 0 ? Math.min(4, targets.length) : 2)
+    : intensity === 'light'
+      ? 1
+      : 0;
+  const requiredSecondarySources = intensity === 'deep' ? 1 : 0;
+  const requiredTargetCoverage = intensity === 'deep'
+    ? targets.length
+    : intensity === 'light'
+      ? Math.min(targets.length, 1)
+      : 0;
+  const requiredPrimaryTargetCoverage = intensity === 'deep'
+    ? targets.length
+    : 0;
+
+  const missing = [];
+  if (primary.length < requiredPrimarySources) {
+    missing.push(
+      `Need ${requiredPrimarySources} primary source open/fetch/inspect step(s); have ${primary.length}.`,
+    );
+  }
+  if (secondary.length < requiredSecondarySources && primary.length < requiredPrimarySources) {
+    missing.push('Need at least one search lead before finishing deep research.');
+  }
+  if (targets.length > 0 && coveredTargets.length < requiredTargetCoverage) {
+    missing.push(
+      `Need evidence for: ${uncoveredTargets.slice(0, 4).join('; ') || targets.slice(0, 4).join('; ')}.`,
+    );
+  }
+  if (targets.length > 0 && primaryCoveredTargets.length < requiredPrimaryTargetCoverage) {
+    missing.push(
+      `Need primary-source evidence for: ${primaryUncoveredTargets.slice(0, 4).join('; ') || targets.slice(0, 4).join('; ')}.`,
+    );
+  }
+  if (intensity === 'deep' && primary.length === 0 && secondary.length > 0) {
+    missing.push('Search snippets alone are not enough; open primary sources for the key claims.');
+  }
+  if (intensity === 'light' && primary.length === 0 && secondary.length === 0) {
+    missing.push('Need at least one successful search or primary-source check before finishing.');
+  }
+
+  const adequate = intensity === 'none' ? true : missing.length === 0;
+  const nextActions = [];
+  if (!adequate) {
+    if (primaryUncoveredTargets.length > 0) {
+      nextActions.push(
+        `Open or fetch primary sources for each remaining target: ${primaryUncoveredTargets.slice(0, 4).join('; ')}.`,
+      );
+    } else if (uncoveredTargets.length > 0) {
+      nextActions.push(
+        `Research each remaining target separately: ${uncoveredTargets.slice(0, 4).join('; ')}.`,
+      );
+    }
+    if (primary.length < requiredPrimarySources) {
+      nextActions.push('Open or fetch primary pages/docs for the remaining claims instead of guessing from memory or snippets.');
+    }
+    if (secondary.length === 0 && intensity === 'deep') {
+      nextActions.push('Run targeted searches, then open the strongest sources.');
+    }
+  }
+
+  return {
+    intensity,
+    adequate,
+    requiredPrimarySources,
+    requiredSecondarySources,
+    requiredTargetCoverage,
+    requiredPrimaryTargetCoverage,
+    primarySourceCount: primary.length,
+    secondarySourceCount: secondary.length,
+    targets,
+    coveredTargets,
+    primaryCoveredTargets,
+    uncoveredTargets,
+    primaryUncoveredTargets,
+    missing,
+    nextActions,
+    reason: adequate
+      ? (intensity === 'none'
+        ? 'No research burden for this run.'
+        : 'Research evidence covers the requested targets.')
+      : clampResearchText(missing.join(' ') || 'Research evidence is still incomplete.', 320),
+  };
+}
+
+function formatResearchAdequacyGuidance(assessment = null) {
+  if (!assessment || assessment.adequate !== false) return '';
+  const lines = [
+    'Research self-check: evidence is still incomplete for this run.',
+    assessment.reason ? `Gap: ${assessment.reason}` : '',
+    assessment.nextActions?.length
+      ? `Next safe steps:\n- ${assessment.nextActions.join('\n- ')}`
+      : '',
+    'Do not complete with memory, guesses, or a partial comparison while these gaps remain. Gather the missing evidence first, or return a blocker that names exactly what could not be verified.',
+  ];
+  return lines.filter(Boolean).join('\n');
+}
+
 function isSubstantiveProgressEvidence(item = {}) {
   if (!isSubstantiveProgressToolName(item.toolName)) return false;
   if (item.evidenceSource === 'messaging') return false;
@@ -274,9 +624,13 @@ function buildAutonomousRecoveryContext({ err, toolExecutions = [], tools = [],
 module.exports = {
   classifyToolExecution,
   deriveEvidenceSource,
+  assessResearchAdequacy,
+  extractResearchTargets,
+  formatResearchAdequacyGuidance,
   gatheredNewEvidence,
   isSubstantiveProgressEvidence,
   isSubstantiveProgressToolName,
+  resolveResearchIntensity,
   summarizeProgressToolExecutions,
   summarizeToolExecutions,
   summarizeAvailableTools,