neoagent 3.2.1-beta.0 → 3.2.1-beta.10

package/server/services/ai/toolEvidence.js

@@ -34,30 +34,50 @@ const EVIDENCE_SOURCE_RULES = [
   { source: 'subagent', match: (name) => name.includes('subagent') },
 ];
 
+const STATE_CHANGING_DEVICE_TOOLS = new Set([
+  'android_install_apk',
+  'android_long_press',
+  'android_open_app',
+  'android_open_intent',
+  'android_press_key',
+  'android_start_emulator',
+  'android_stop_emulator',
+  'android_swipe',
+  'android_tap',
+  'android_type',
+  'desktop_click',
+  'desktop_drag',
+  'desktop_launch_app',
+  'desktop_press_key',
+  'desktop_scroll',
+  'desktop_select_device',
+  'desktop_type',
+]);
+
 function deriveEvidenceSource(name) {
   const rule = EVIDENCE_SOURCE_RULES.find((entry) => entry.match(name));
   return rule ? rule.source : 'tool';
 }
 
-function classifyToolExecution(toolName, toolArgs = {}, result, errorMessage = '') {
+function resolveDeclaredToolAccess(toolDefinition, toolArgs = {}) {
+  const access = String(toolDefinition?.access || '').trim().toLowerCase();
+  if (access === 'read' || access === 'write') return access;
+  if (access !== 'dynamic_http_method') return null;
+
+  const method = String(toolArgs?.method || toolArgs?.http_method || 'GET')
+    .trim()
+    .toUpperCase();
+  return ['GET', 'HEAD', 'OPTIONS'].includes(method) ? 'read' : 'write';
+}
+
+function classifyToolExecution(
+  toolName,
+  toolArgs = {},
+  result,
+  errorMessage = '',
+  toolDefinition = null,
+) {
   const name = String(toolName || '');
-  const evidenceRelevantPrefixes = ['browser_', 'android_'];
-  const evidenceRelevantExact = new Set([
-    'web_search',
-    'http_request',
-    'read_file',
-    'read_files',
-    'search_files',
-    'list_directory',
-    'code_navigate',
-    'query_structured_data',
-    'session_search',
-    'memory_recall',
-    'analyze_image',
-    'read_health_data',
-    'list_tasks',
-    'wait_subagent',
-  ]);
   const stateChangingExact = new Set([
     'execute_command',
     'write_file',
@@ -79,22 +99,30 @@ function classifyToolExecution(toolName, toolArgs = {}, result, errorMessage = '
     'mcp_add_server',
     'mcp_remove_server',
     'spawn_subagent',
+    'delegate_to_agent',
     'cancel_subagent',
   ]);
 
-  const evidenceSource = deriveEvidenceSource(name);
+  const declaredAccess = resolveDeclaredToolAccess(toolDefinition, toolArgs);
+  const evidenceSource = declaredAccess ? 'integration' : deriveEvidenceSource(name);
 
-  const evidenceRelevant = evidenceRelevantExact.has(name)
-    || evidenceRelevantPrefixes.some((prefix) => name.startsWith(prefix));
-  const stateChanged = (
-    name === 'execute_command'
-      ? !isClearlyReadOnlyShellCommand(toolArgs?.command || '')
-      : stateChangingExact.has(name)
-  )
+  // Any successful, substantive tool result can advance the run. This default
+  // is deliberate: MCP, skills, and newly added integrations must not become
+  // invisible to the churn guard just because their names were not added to a
+  // central allow-list. Repetition detection still rejects unchanged retries.
+  const evidenceRelevant = isSubstantiveProgressToolName(name);
+  let directStateChange;
+  if (name === 'execute_command' || name === 'android_shell') {
+    directStateChange = !isClearlyReadOnlyShellCommand(toolArgs?.command || '');
+  } else {
+    directStateChange = declaredAccess === 'write'
+      || STATE_CHANGING_DEVICE_TOOLS.has(name)
+      || stateChangingExact.has(name);
+  }
+  const stateChanged = directStateChange
     || (name.startsWith('github_') && isProgressToolCall(name, toolArgs))
     || (name === 'http_request' && isProgressToolCall(name, toolArgs))
-    || name.startsWith('android_')
-    || ['browser_click', 'browser_type', 'browser_evaluate'].includes(name);
+    || ['browser_click', 'browser_evaluate', 'browser_navigate', 'browser_type'].includes(name);
 
   let normalizedError = String(errorMessage || result?.error || '').trim();
   if (!normalizedError && name === 'execute_command' && result && typeof result === 'object') {
@@ -167,11 +195,300 @@ function gatheredNewEvidence(execution, repetitionObservation = null) {
 function isSubstantiveProgressToolName(toolName = '') {
   const name = String(toolName || '').trim();
   if (!name) return false;
-  if (name === 'send_message' || name === 'send_interim_update' || name === 'make_call') return false;
+  if (name === 'send_message' || name === 'send_interim_update' || name === 'make_call' || name === 'notify_user') return false;
   if (name === 'think' || name === 'activate_tools' || name === 'task_complete') return false;
   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;
+}
+
+// Research targets come from structured task analysis / goal contract only.
+// Do not NLP-extract entity names from free text.
+function collectResearchTargets(analysis = null, goalContext = null) {
+  return uniqueResearchTokens([
+    ...(Array.isArray(analysis?.research_targets) ? analysis.research_targets : []),
+    ...(Array.isArray(goalContext?.researchTargets) ? goalContext.researchTargets : []),
+  ], { limit: 8 });
+}
+
+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;
+    // Tool-schema identity only: family prefixes, not free-text phrase matching.
+    return tool.startsWith('browser_') || tool.startsWith('mcp_');
+  });
+}
+
+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;
@@ -246,12 +563,16 @@ function buildAutonomousRecoveryContext({ err, toolExecutions = [], tools = [],
 module.exports = {
   classifyToolExecution,
   deriveEvidenceSource,
+  assessResearchAdequacy,
+  formatResearchAdequacyGuidance,
   gatheredNewEvidence,
   isSubstantiveProgressEvidence,
   isSubstantiveProgressToolName,
+  resolveResearchIntensity,
   summarizeProgressToolExecutions,
   summarizeToolExecutions,
   summarizeAvailableTools,
   inferToolFailureMessage,
   buildAutonomousRecoveryContext,
+  resolveDeclaredToolAccess,
 };