@velaro/mcp-server 2.0.0 → 2.0.2

package/tool-annotations.js

@@ -16,59 +16,47 @@ const READ_TOKENS = new Set([
 
 // Names that contain a read-looking token but change state (checked before READ_TOKENS).
 const MUTATING = new Set([
-  'report_schedule_upsert', 'report_subscription_update', 'report_subscription_delete', 'report_export_start',
-  'report_backfill', 'report_data_export', 'executive_insights_subscribe', 'velaro_diagnostic_start',
-  'apple_test_control', 'kb_capture_screenshot', 'business_action_route', 'business_action_execute',
-  'netsuite_cti_generate_url', 'netsuite_m2m_init', 'netsuite_m2m_save', 'index_integrity_repair',
-  'klaviyo_migration_run', 'sitesync_blob_push', 'sitesync_blob_import', 'chat_intelligence_draft_article',
-  'teams_phone_set_config', 'webflow_set_config', 'notion_set_config', 'monday_set_field_mapping',
-  'teams_push_settings_update', 'teams_channel_config_update', 'routing_team_update_config',
-  'pickup_update_config', 'payment_recovery_update_config', 'recruiting_sync_jobs',
-  'ai_config_set_reply_format', 'ai_model_set_site_thinking', 'ai_model_set_site_pin',
-  'entitlement_reconcile', 'entitlement_sync_stripe', 'entitlement_backfill_subscriptions',
-  'calendly_configure', 'acuity_configure', 'ms_bookings_configure',
+  'report_schedule_upsert', 'report_subscription_update', 'report_subscription_delete',
+  'report_export_start', 'report_backfill', 'report_data_export', 'executive_insights_subscribe',
+  'velaro_diagnostic_start', 'business_action_route', 'business_action_execute', 'netsuite_cti_generate_url',
+  'netsuite_m2m_init', 'netsuite_m2m_save', 'index_integrity_repair', 'klaviyo_migration_run',
+  'chat_intelligence_draft_article', 'teams_phone_set_config', 'webflow_set_config', 'notion_set_config',
+  'monday_set_field_mapping', 'teams_push_settings_update', 'teams_channel_config_update',
+  'routing_team_update_config', 'pickup_update_config', 'payment_recovery_update_config',
+  'recruiting_sync_jobs', 'ai_config_set_reply_format', 'magento_set_sidebar_fields',
   'zoom_phone_set_config',
 ]);
 
 // Names that look like writes but only read (checked before the write rules).
 const READ_ONLY_EXPLICIT = new Set([
-  'activity_logs', 'ai_field_extraction_fields', 'billing_subscription_invoice_send_log', 'billing_subscription_recognition_schedule',
-  'billing_subscription_payment_history', 'billing_subscription_invoice_history', 'billing_subscription_subscription_history',
-  'billing_subscription_upcoming', 'cobrowse_show', 'keyword_intelligence_top', 'keyword_intelligence_conversations',
-  'knowledge_advisor_advise', 'migrate_export', 'migrate_workflows_list', 'migrate_rules_list', 'quality_sentiment',
-  'quality_agent_performance', 'quality_low_scores', 'quality_calibration',
-  'appointments_find_open_slots', 'appointments_list', 'compliance_redaction_test', 'compliance_status',
-  'compliance_signatures', 'compliance_redaction_events', 'compliance_redaction_status',
-  'shopify_widget_activation_url', 'klaviyo_savings_calculator', 'routing_simulate_inactivity',
-  'outlook_calendar_get_available_range', 'ms_bookings_check_availability_range', 'copilot_studio_test',
-  'notion_test_token', 'teams_phone_test_config', 'webflow_test_config', 'magento_test_connection',
-  'outlook_calendar_test_connection', 'scraper_verify_token', 'bigcommerce_check_refundable',
-  'sitesync_blob_list', 'kb_advise_knowledge_strategy', 'index_move_status', 'index_mixed_content',
-  'index_search', 'netsuite_m2m_verify', 'bot_skill_usage', 'bot_full_diagnostic', 'bot_recent_errors',
-  'logs_loggly_search', 'logs_appinsights_query', 'velaro_logs_search', 'executive_brief', 'friction_radar',
-  'tour_insights', 'kpi_snapshot', 'site_info', 'case_board', 'case_list_types', 'ai_spend_report',
-  'agent_availability_report', 'missed_chat_diagnostics', 'sse_visitor_diagnostic', 'signalr_diagnostics',
-  'ivr_agent_availability', 'contactlist_get', 'ai_model_resolver_map', 'ai_model_effective_for_site',
-  'calendly_get_status', 'acuity_get_status', 'outlook_calendar_status', 'ms_bookings_status',
-  'service_level_report', 'call_activity_report', 'callrail_get_attributions',
-  'product_sync_status', 'report_export_status', 'report_data_export', 'coupon_grant_list', 'coupon_grant_get',
-  'automation_draft_list', 'focus_get_draft_pregeneration_report', 'teams_push_settings_get',
-  'call_center_team_breakdown', 'call_center_channel_breakdown', 'outbound_activity_for_contact',
-  'integration_skill_logs', 'support_integration_logs', 'site_integration_logs', 'magento_activity_logs',
-  'support_site_deployments', 'support_schedule_adherence', 'support_site_agents', 'support_site_activity',
-  'chat_intelligence_themes', 'chat_intelligence_recommendations', 'index_move_preview', 'index_split_preview',
-  'canned_learning_suggestions', 'canned_learning_teams', 'canned_learning_edit_summary',
-  'chat_topics_group_suggestions', 'chat_topics_suggestions', 'enterprise_reports', 'image_analysis_limits',
-  'avatar_session_readiness', 'recruiting_ats_failures', 'jobboard_application_history',
-  'recruiting_download_resume', 'routing_inactivity_transfers', 'entitlement_enterprise_reports_package',
-  'compliance_attestation', 'livefluence_conversion_advisor', 'copilot_studio_ask',
-  'skill_routing_simulate', 'squarespace_test_connection', 'woocommerce_logs', 'site_builder_connect_info',
+  'activity_logs', 'ai_field_extraction_fields', 'keyword_intelligence_top',
+  'keyword_intelligence_conversations', 'knowledge_advisor_advise', 'quality_sentiment',
+  'quality_agent_performance', 'quality_low_scores', 'quality_calibration', 'appointments_find_open_slots',
+  'appointments_list', 'compliance_redaction_test', 'compliance_status', 'compliance_signatures',
+  'compliance_redaction_events', 'compliance_redaction_status', 'shopify_widget_activation_url',
+  'klaviyo_savings_calculator', 'routing_simulate_inactivity', 'outlook_calendar_get_available_range',
+  'ms_bookings_check_availability_range', 'copilot_studio_test', 'notion_test_token',
+  'teams_phone_test_config', 'webflow_test_config', 'magento_test_connection', 'scraper_verify_token',
+  'kb_advise_knowledge_strategy', 'index_move_status', 'index_mixed_content', 'index_search',
+  'netsuite_m2m_verify', 'bot_skill_usage', 'bot_recent_errors', 'executive_brief', 'friction_radar',
+  'kpi_snapshot', 'site_info', 'case_board', 'case_list_types', 'ivr_agent_availability', 'contactlist_get',
+  'service_level_report', 'call_activity_report', 'callrail_get_attributions', 'product_sync_status',
+  'report_export_status', 'report_data_export', 'automation_draft_list',
+  'focus_get_draft_pregeneration_report', 'teams_push_settings_get', 'call_center_team_breakdown',
+  'call_center_channel_breakdown', 'outbound_activity_for_contact', 'integration_skill_logs',
+  'magento_activity_logs', 'chat_intelligence_themes', 'chat_intelligence_recommendations',
+  'index_move_preview', 'index_split_preview', 'canned_learning_suggestions', 'canned_learning_teams',
+  'canned_learning_edit_summary', 'chat_topics_group_suggestions', 'chat_topics_suggestions',
+  'enterprise_reports', 'recruiting_ats_failures', 'jobboard_application_history',
+  'recruiting_download_resume', 'routing_inactivity_transfers', 'compliance_attestation',
+  'copilot_studio_ask', 'skill_routing_simulate', 'squarespace_test_connection', 'woocommerce_logs',
+  'site_builder_connect_info',
 ]);
 
 // Write tools that are additive even though their name carries a destructive-looking token.
 const NON_DESTRUCTIVE_EXPLICIT = new Set([
-  'safety_settings_test', 'safety_need_help', 'canned_learning_record_edit', 'hangfire_retry_job',
-  'netsuite_suiteapp_download', 'chat_topics_reclassify',
+  'safety_settings_test', 'safety_need_help', 'canned_learning_record_edit', 'netsuite_suiteapp_download',
+  'chat_topics_reclassify',
 ]);
 
 const DESTRUCTIVE_TOKENS = new Set([
@@ -93,14 +81,12 @@ const NOT_IDEMPOTENT_TOKENS = new Set([
 ]);
 
 // Tools that reach a system outside the caller's Velaro account (third-party APIs, email/SMS/chat delivery, CRMs).
-const OPEN_WORLD = new RegExp('^(' + [
-  'calendly', 'acuity', 'outlook', 'ms_bookings', 'bigcommerce', 'shopify', 'magento', 'sap', 'netsuite',
-  'monday', 'notion', 'teams', 'slack', 'webflow', 'klaviyo', 'callrail', 'copilot_studio', 'scraper',
-  'site_scraper', 'apple', 'mobile_ota', 'code_push', 'jobboard', 'recruiting', 'payment_recovery',
-  'pickup_notify', 'email_queue_replay', 'email_inbox', 'entitlement_sync_stripe', 'logs_loggly',
-  'logs_appinsights', 'livefluence', 'telephony', 'kb_capture_screenshot', 'business_action',
-  'sitesync', 'email_delivery', 'campaign_sender_auth', 'ivr_update_line',
-].join('|') + ')');
+const OPEN_WORLD_PREFIXES = [
+  'outlook', 'ms_bookings', 'shopify', 'magento', 'netsuite', 'monday', 'notion', 'teams', 'slack',
+  'webflow', 'klaviyo', 'callrail', 'copilot_studio', 'scraper', 'apple', 'jobboard', 'recruiting',
+  'payment_recovery', 'pickup_notify', 'telephony', 'business_action', 'campaign_sender_auth',
+  'ivr_update_line',
+];
 
 const ACRONYMS = {
   kb: 'KB', ai: 'AI', ivr: 'IVR', sap: 'SAP', crm: 'CRM', sse: 'SSE', api: 'API', cti: 'CTI', m2m: 'M2M',
@@ -117,29 +103,45 @@ export function titleFor(name) {
     .join(' ');
 }
 
-export function annotationsFor(name) {
-  const t = tokens(name);
-  const has = (set) => t.some((x) => set.has(x));
-  const readOnly = READ_ONLY_EXPLICIT.has(name)
-    || (!MUTATING.has(name) && has(READ_TOKENS) && !has(DESTRUCTIVE_TOKENS) && !has(ADDITIVE_TOKENS));
-  const openWorldHint = OPEN_WORLD.test(name);
-  if (readOnly) {
-    return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint };
+// Builds the rule set. The public package uses the base rules only; mcp/staff-tool-annotations.js (never
+// published) adds the staff tools' entries, so no staff tool name ships in this file (guard:
+// scripts/validate-mcp-no-staff-tools.js).
+export function makeAnnotator(extra = {}) {
+  const mutating = new Set([...MUTATING, ...(extra.mutating ?? [])]);
+  const readOnlyExplicit = new Set([...READ_ONLY_EXPLICIT, ...(extra.readOnly ?? [])]);
+  const nonDestructiveExplicit = new Set([...NON_DESTRUCTIVE_EXPLICIT, ...(extra.nonDestructive ?? [])]);
+  const openWorld = new RegExp('^(' + [...OPEN_WORLD_PREFIXES, ...(extra.openWorldPrefixes ?? [])].join('|') + ')');
+
+  function annotationsFor(name) {
+    const t = tokens(name);
+    const has = (set) => t.some((x) => set.has(x));
+    const readOnly = readOnlyExplicit.has(name)
+      || (!mutating.has(name) && has(READ_TOKENS) && !has(DESTRUCTIVE_TOKENS) && !has(ADDITIVE_TOKENS));
+    const openWorldHint = openWorld.test(name);
+    if (readOnly) {
+      return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint };
+    }
+    const additive = nonDestructiveExplicit.has(name) || (has(ADDITIVE_TOKENS) && !has(DESTRUCTIVE_TOKENS));
+    return {
+      readOnlyHint: false,
+      destructiveHint: !additive,
+      idempotentHint: !has(NOT_IDEMPOTENT_TOKENS),
+      openWorldHint,
+    };
   }
-  const additive = NON_DESTRUCTIVE_EXPLICIT.has(name) || (has(ADDITIVE_TOKENS) && !has(DESTRUCTIVE_TOKENS));
-  return {
-    readOnlyHint: false,
-    destructiveHint: !additive,
-    idempotentHint: !has(NOT_IDEMPOTENT_TOKENS),
-    openWorldHint,
-  };
-}
 
-// Returns the tool with `title` and `annotations` filled in; a hand-written value on the tool wins.
-export function withAnnotations(tool) {
-  return {
-    ...tool,
-    title: tool.title ?? titleFor(tool.name),
-    annotations: { ...annotationsFor(tool.name), ...(tool.annotations ?? {}) },
-  };
+  // Returns the tool with `title` and `annotations` filled in; a hand-written value on the tool wins.
+  function withAnnotations(tool) {
+    return {
+      ...tool,
+      title: tool.title ?? titleFor(tool.name),
+      annotations: { ...annotationsFor(tool.name), ...(tool.annotations ?? {}) },
+    };
+  }
+
+  return { annotationsFor, withAnnotations };
 }
+
+const BASE = makeAnnotator();
+export const annotationsFor = BASE.annotationsFor;
+export const withAnnotations = BASE.withAnnotations;

package/log-search.js

@@ -1,252 +0,0 @@
-// Complete Velaro Logger reads (2026-10-14).
-//
-// WHY: velaro-messaging's /superadmin/logs/search and /internal/logs/search silently under-reported text queries.
-// Proven live that day: q=[HttpFallback] over 3.9 h returned 0-2 rows while 136 existed, and q=AsrsNegotiateFailed
-// (no level) returned 0 while 4 existed. The AI-search path only saw the newest 1,000 candidates and its answer was
-// final; the exact path only saw the newest 5,000 rows of the window before filtering. Neither said so.
-//
-// TWO MODES, picked automatically from the first response:
-//  * CURSOR mode (server with velaro-messaging PR #2510, response carries `truncated`/`scannedRows`): the server scans the
-//    window newest-first applying level/site AND text (as an escaped regex, which also forces the exact path) while it
-//    scans, reports `truncated`, and returns `nextCursor` whenever more rows may exist. We follow the cursor until it is
-//    null, so a 2 h window is a handful of requests instead of hundreds.
-//  * BISECT mode (older server): never send q=; push level/site/etc server side; includeTotal=true reports
-//    totalCountCapped for a slice; a capped slice is bisected until none is capped; text is filtered client side.
-// Either way the result says COMPLETE or INCOMPLETE, so a 0 is never ambiguous. Hard caps: maxRequests and maxSeconds.
-//
-// KEEP IN SYNC: this file is duplicated byte for byte in mcp/log-search.js (the npm packages ship separately);
-// cli/lib/log-search.test.js fails if the two copies drift.
-
-const MIN_SLICE_MS = 2000;
-
-export const escapeRegex = (s) => String(s).replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const tsOf = (e) => { const t = Date.parse(e.timestamp ?? e.LogTimestamp ?? ''); return Number.isNaN(t) ? 0 : t; };
-
-/**
- * fetch that retries ONLY 429 (honouring Retry-After, seconds, capped at 30 s) for up to `retries` attempts and returns the final Response.
- * `init` may be a function so each attempt gets a fresh AbortSignal.
- */
-export async function fetchRetry429(url, init = {}, { retries = 3, fetchImpl = fetch, sleepImpl = sleep } = {}) {
-  for (let attempt = 0; ; attempt++) {
-    const res = await fetchImpl(url, typeof init === 'function' ? init() : init);
-    if (res.status === 429 && attempt < retries) {
-      // Number(null) is 0, which would turn a 429 without Retry-After into an immediate retry: a missing header means the 5 s default.
-      const raw = res.headers?.get?.('retry-after');
-      const ra = raw == null || raw === '' ? NaN : Number(raw);
-      await sleepImpl(Math.min(Number.isFinite(ra) && ra >= 0 ? ra : 5, 30) * 1000);
-      continue;
-    }
-    return res;
-  }
-}
-
-/** fetchRetry429 + JSON. Any non-2xx throws an Error carrying `.status` and the response text. */
-export async function fetchJsonRetry(url, init = {}, opts = {}) {
-  const res = await fetchRetry429(url, init, opts);
-  if (!res.ok) {
-    const err = new Error(`HTTP ${res.status}: ${(await res.text().catch(() => '')).slice(0, 400)}`);
-    err.status = res.status;
-    throw err;
-  }
-  return res.json();
-}
-
-/**
- * @param {object} o
- * @param {(query: string) => Promise<any>} o.fetchJson  GET `...search?<query>` and return parsed JSON (caller adds auth/timeout)
- * @param {Date} o.from
- * @param {Date} o.to
- * @param {object} [o.params]  server-side filters: level, siteId, source, integration, platform, environment, correlationId
- * @param {string} [o.contains] case-insensitive substring of the message
- * @param {string} [o.regex]    regex on the message
- * @param {string} [o.logger]   substring of the logger name
- * @param {number} [o.maxRequests=200]
- * @param {number} [o.maxSeconds=120]   wall-clock budget for the whole read
- * @param {number} [o.wanted=Infinity]  CURSOR mode: stop once this many matches were collected (newest first); the result is then `satisfied`
- */
-export async function completeLogSearch({ fetchJson, from, to, params = {}, contains, regex, logger, maxRequests = 200, maxSeconds = 120, wanted = Infinity }) {
-  const server = {};
-  for (const k of ['level', 'siteId', 'source', 'integration', 'platform', 'environment', 'correlationId']) {
-    if (params[k] !== undefined && params[k] !== null && params[k] !== '') server[k] = String(k === 'level' ? String(params[k]).toUpperCase() : params[k]);
-  }
-  const byId = new Map();
-  const unresolved = [];
-  const started = Date.now();
-  let requests = 0;
-  let slices = 0;
-  let scanned = 0;
-  let budgetExhausted = false;
-  let timeExhausted = false;
-
-  const canRequest = () => {
-    if (requests >= maxRequests) { budgetExhausted = true; return false; }
-    if ((Date.now() - started) / 1000 >= maxSeconds && requests > 0) { timeExhausted = true; return false; }
-    return true;
-  };
-  const norm = (r) => (Array.isArray(r) ? { entries: r } : (r || {}));
-  const add = (e) => byId.set(e.id ?? `${e.timestamp}|${e.message}`, e);
-
-  // ---- text handling shared by both modes ----
-  const textQ = regex ?? (contains ? escapeRegex(contains) : undefined);
-  const textLogger = logger ? escapeRegex(logger) : undefined;
-
-  // ---- probe: first CURSOR-mode page, doubles as the new-server detector ----
-  const cursorQuery = (cursor) => {
-    const q = new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), take: '500', ...server });
-    if (textQ) q.set('q', textQ);
-    if (textLogger) q.set('logger', textLogger);
-    if (textQ || textLogger) q.set('regex', 'true'); // regex also forces the exact path (the AI-search path is never consulted)
-    q.set('fallthrough', 'false');
-    if (cursor) q.set('cursor', cursor);
-    return q.toString();
-  };
-
-  let mode = 'bisect';
-  let satisfied = false;
-  let cursorDone = false;
-
-  if (canRequest()) {
-    requests++;
-    const probe = norm(await fetchJson(cursorQuery(null)));
-    if (typeof probe.truncated === 'boolean') {
-      mode = 'cursor';
-      scanned += Number(probe.scannedRows ?? 0);
-      for (const e of probe.entries ?? []) add(e);
-      let page = probe;
-      let cursor = probe.nextCursor || null;
-      for (;;) {
-        // The ONLY way a cursor read is COMPLETE: the last page said truncated === false and carried no cursor. `truncated: true` with no
-        // cursor means the server stopped scanning (deadline/cap) and could not say where to continue: INCOMPLETE, never COMPLETE.
-        if (!cursor) {
-          if (page.truncated === false) cursorDone = true;
-          else unresolved.push('the server stopped scanning (truncated) without a cursor to continue from');
-          break;
-        }
-        if (byId.size >= wanted) { satisfied = true; break; }
-        if (!canRequest()) { unresolved.push(`cursor ${cursor} (${timeExhausted ? 'time budget' : 'request budget'})`); break; }
-        requests++;
-        const next = norm(await fetchJson(cursorQuery(cursor)));
-        scanned += Number(next.scannedRows ?? 0);
-        for (const e of next.entries ?? []) add(e);
-        if (next.nextCursor && next.nextCursor === cursor) {
-          unresolved.push('no progress: the server returned the cursor it was given (its scan budget ended before reaching any row)');
-          break;
-        }
-        page = next;
-        cursor = next.nextCursor || null;
-      }
-      slices = 1;
-    }
-  }
-
-  // ---- BISECT mode (older server) ----
-  if (mode === 'bisect' && !budgetExhausted) {
-    const call = async (a, b, cursor, total) => {
-      if (!canRequest()) return null;
-      requests++;
-      const q = new URLSearchParams({ from: a.toISOString(), to: b.toISOString(), take: '500', ...server });
-      if (total) q.set('includeTotal', 'true');
-      if (cursor) q.set('cursor', cursor);
-      return norm(await fetchJson(q.toString()));
-    };
-    const walk = async (a, b) => {
-      const r = await call(a, b, null, true);
-      if (!r) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (${timeExhausted ? 'time' : 'request'} budget)`); return; }
-      if (r.totalCountCapped === true && (b - a) > MIN_SLICE_MS) {
-        const mid = new Date(a.getTime() + Math.floor((b - a) / 2));
-        await walk(a, mid);
-        await walk(mid, b);
-        return;
-      }
-      if (r.totalCountCapped === true) unresolved.push(`${a.toISOString()}..${b.toISOString()} (still capped at <=2s: a log storm; add level/site)`);
-      slices++;
-      scanned += Number(r.totalCount ?? (r.entries?.length ?? 0));
-      for (const e of r.entries ?? []) add(e);
-      let cursor = r.nextCursor;
-      while (cursor) {
-        const r2 = await call(a, b, cursor, false);
-        if (!r2) { unresolved.push(`${a.toISOString()}..${b.toISOString()} (budget while paging)`); break; }
-        for (const e of r2.entries ?? []) add(e);
-        cursor = r2.nextCursor;
-      }
-    };
-    await walk(from, to);
-  }
-
-  let rows = [...byId.values()];
-  const msg = (e) => String(e.message ?? e.Message ?? '');
-  if (mode === 'bisect') {
-    if (contains) { const c = contains.toLowerCase(); rows = rows.filter((e) => msg(e).toLowerCase().includes(c)); }
-    if (regex) { const re = new RegExp(regex, 'i'); rows = rows.filter((e) => re.test(msg(e))); }
-    if (logger) { const l = logger.toLowerCase(); rows = rows.filter((e) => String(e.logger ?? e.Logger ?? '').toLowerCase().includes(l)); }
-  }
-  rows.sort((x, y) => tsOf(y) - tsOf(x)); // compare as instants: fractional-second digit counts differ between rows
-
-  const complete = mode === 'cursor' ? (cursorDone && unresolved.length === 0) : (unresolved.length === 0 && !budgetExhausted && !timeExhausted);
-  return { entries: rows, fetched: byId.size, scanned, requests, slices, mode, complete, satisfied, unresolved, budgetExhausted, timeExhausted };
-}
-
-/** One line a human or an LLM can trust: says COMPLETE or INCOMPLETE and how much the SERVER actually scanned. */
-export function describeCompleteness(r) {
-  const base = `${r.entries.length} matched (${r.fetched} fetched; server scanned ${r.scanned} rows) in ${r.requests} request(s), ${r.mode} mode`;
-  if (r.satisfied) return `${base}; showing the newest matches, more may exist beyond what was asked for (stopped early on purpose).`;
-  return r.complete
-    ? `${base}; COMPLETE (the whole window was covered), so 0 matches means nothing was logged.`
-    : `${base}; INCOMPLETE (${r.unresolved.length} part(s) not covered${r.budgetExhausted ? ', request budget exhausted' : ''}${r.timeExhausted ? ', time budget exhausted' : ''}): narrow the window or add level/site; a short or empty result is NOT proof of absence.`;
-}
-
-/** For raw (server-side q=) responses: surfaces searchPath/scannedRows/truncated so a 0 is never ambiguous. */
-export function describeRawMeta(resp) {
-  if (!resp || Array.isArray(resp) || resp.scannedRows === undefined) {
-    return 'server did not report scan metadata (older deploy): treat an empty or short result as unverified, use the complete mode.';
-  }
-  const t = resp.truncated === true;
-  // exact=false: the answer involves the AI-search index, which is best-effort (written behind, can lag, misses text that starts mid-word).
-  const bestEffort = resp.exact === false ? ' exact=false (answered from the best-effort search index: it can lag and misses text that starts mid-word, so treat counts as a floor, not exact)' : '';
-  return `searchPath=${resp.searchPath} scannedRows=${resp.scannedRows} truncated=${t}${t ? ' (NOT proof of absence; continue with nextCursor or narrow the window)' : ''}${bestEffort}${resp.nextCursor ? ' nextCursor=present' : ''}`;
-}
-
-// ── Time window + raw query building (shared by server.js and staff-server.js velaro_logs_search) ──
-// Bug fixed 2026-10-21: the tool only honored `last` and silently ignored from/to, so an explicit
-// historical range returned the newest entries instead. from/to accept an ISO timestamp or a
-// relative duration (30m, 2h, 1d = that long ago). `to` defaults to now, `from` to to - last (2h).
-const DUR_RE = /^(\d+)(m|h|d)$/i;
-const durMs = (s) => {
-  const m = DUR_RE.exec(String(s).trim());
-  const n = parseInt(m[1], 10);
-  const u = m[2].toLowerCase();
-  return u === 'm' ? n * 60000 : u === 'h' ? n * 3600000 : n * 86400000;
-};
-function parseWhen(label, v, nowMs) {
-  const s = String(v).trim();
-  if (DUR_RE.test(s)) return new Date(nowMs - durMs(s));
-  const d = new Date(s);
-  if (Number.isNaN(d.getTime())) throw new Error(`Invalid ${label} "${v}": use an ISO timestamp (2026-10-20T00:00:00Z) or a relative duration like 2h.`);
-  return d;
-}
-export function resolveLogWindow(args = {}, nowMs = Date.now()) {
-  const given = (v) => v !== undefined && v !== null && String(v).trim() !== '';
-  const to = given(args.to) ? parseWhen('to', args.to, nowMs) : new Date(nowMs);
-  const lastMs = DUR_RE.test(String(args.last ?? '').trim()) ? durMs(args.last) : 2 * 3600000;
-  const from = given(args.from) ? parseWhen('from', args.from, nowMs) : new Date(to.getTime() - lastMs);
-  if (from.getTime() >= to.getTime()) throw new Error(`Invalid window: from (${from.toISOString()}) must be before to (${to.toISOString()}).`);
-  return { from, to };
-}
-
-// Query string for GET /superadmin/logs/search (same params as /internal/logs/search).
-export function buildRawLogQuery(args, from, to) {
-  const params = new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), take: String(args.take ?? 50) });
-  if (args.q)             params.set('q',             args.q);
-  if (args.level)         params.set('level',         String(args.level).toUpperCase());
-  if (args.logger)        params.set('logger',        args.logger);
-  if (args.integration)   params.set('integration',   args.integration);
-  if (args.siteId)        params.set('siteId',        String(args.siteId));
-  if (args.source)        params.set('source',        args.source);
-  if (args.platform)      params.set('platform',      args.platform);
-  if (args.environment)   params.set('environment',   args.environment);
-  if (args.correlationId) params.set('correlationId', args.correlationId);
-  if (args.regex)         params.set('regex',         'true');
-  return params.toString();
-}