@mackody/quickenrich-mcp 0.1.0

package/scripts/lib/core.mjs

@@ -0,0 +1,3303 @@
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { Agent as HttpAgent, request as httpRequest } from "node:http";
+import { Agent as HttpsAgent, request as httpsRequest } from "node:https";
+import { homedir } from "node:os";
+import { dirname, extname, join } from "node:path";
+
+export const SERVER_VERSION = "0.1.0";
+export const DEFAULT_API_BASE_URL = "https://app.quickenrich.io";
+export const DOCS_URL = "https://app.quickenrich.io/docs";
+export const DEFAULT_CONFIG_PATH = join(homedir(), ".config", "quickenrich-mcp", "config.json");
+export const DEFAULT_DATA_DIR = join(homedir(), ".cache", "quickenrich-mcp");
+export const MAX_OUTPUT_CHARS = positiveInteger(process.env.QUICKENRICH_MCP_MAX_OUTPUT_CHARS, 12_000);
+
+const DEFAULT_TIMEOUT_MS = positiveInteger(process.env.QUICKENRICH_API_TIMEOUT_MS, 30_000);
+const DEFAULT_RETRY_COUNT = positiveInteger(process.env.QUICKENRICH_API_RETRY_COUNT, 2);
+const DEFAULT_RETRY_BASE_MS = positiveInteger(process.env.QUICKENRICH_API_RETRY_BASE_MS, 250);
+const DEFAULT_RESPONSE_MODE = process.env.QUICKENRICH_MCP_RESPONSE_MODE || "compact";
+const DEFAULT_DOMAIN_SEARCH_RPM = positiveInteger(process.env.QUICKENRICH_DOMAIN_SEARCH_REQUESTS_PER_MINUTE, 300);
+const DEFAULT_DOMAIN_SEARCH_BURST = positiveInteger(process.env.QUICKENRICH_DOMAIN_SEARCH_BURST_SIZE, 8);
+const RESPONSE_MODES = new Set(["compact", "full", "meta"]);
+const PROJECTION_MODES = new Set(["full", "people", "companies", "emails", "phones", "ids"]);
+const CACHE_MODES = new Set(["off", "read", "write", "readwrite", "refresh", "cache_only"]);
+const SERIALIZED_TOOL_PAYLOAD = Symbol("quickenrich.serializedToolPayload");
+
+export const RATE_LIMITS = {
+  employee_search: 1000,
+  phone_search: 1000,
+  reverse_email: 1000,
+  domain_search: 300,
+  contact_finder: 120,
+  company_finder: 120,
+  lookup_values: 0,
+};
+
+const DEFAULT_BURSTS = {
+  employee_search: 16,
+  phone_search: 16,
+  reverse_email: 16,
+  domain_search: DEFAULT_DOMAIN_SEARCH_BURST,
+  contact_finder: 4,
+  company_finder: 4,
+};
+const MAX_BATCH_CONCURRENCY = 32;
+const MAX_EMAIL_BATCH_CONCURRENCY = 128;
+const USE_FETCH_TRANSPORT = /^(1|true|yes|fetch)$/i.test(String(process.env.QUICKENRICH_API_USE_FETCH || ""));
+const SHARED_HTTP_AGENT = new HttpAgent({ keepAlive: true, maxSockets: 256, maxFreeSockets: 64 });
+const SHARED_HTTPS_AGENT = new HttpsAgent({ keepAlive: true, maxSockets: 256, maxFreeSockets: 64 });
+let artifactWriteCounter = 0;
+
+const LOOKUP_PATHS = {
+  country_codes: "/api/lookups/country-codes",
+  industries: "/api/lookups/industries",
+  employee_ranges: "/api/lookups/employee-ranges",
+  revenue_ranges: "/api/lookups/revenue-ranges",
+  company_services: "/api/lookups/company-services",
+};
+
+const RESERVED_EMAIL_TLDS = new Set(["example", "invalid", "localhost", "test"]);
+const FOUNDER_TITLE = "Founder, CEO, Owner, President, Co-Founder, Managing Director";
+const AGENT_TOOL_NAMES = new Set([
+  "quickenrich_auth_status",
+  "quickenrich_agent_graph",
+  "quickenrich_natural_language",
+  "quickenrich_pipeline",
+  "quickenrich_batch_pull_leads",
+  "quickenrich_batch_reverse_email",
+  "quickenrich_batch_employee_search",
+  "quickenrich_reverse_email",
+  "quickenrich_lookup_values",
+]);
+
+const AGENT_TOOL_BRIEFS = {
+  quickenrich_auth_status: "Check auth/config without exposing the API key.",
+  quickenrich_agent_graph: "Compact map of QE tools, routes, limits, credits, and envelope policy.",
+  quickenrich_natural_language: "Plan a QE tool call from plain English; use execute=false for no-spend routing.",
+  quickenrich_pipeline: "Native enrichment workflows with file IO, resume/output artifacts, projections, cache, and budget guards.",
+  quickenrich_batch_pull_leads: "Primary batch lead/company pull: domain_search, contact_finder, company_finder; supports CSV/JSONL, max_credits, resume_state, export.",
+  quickenrich_batch_reverse_email: "Batch reverse-email lookup from emails/CSV/JSONL with dedupe, max_credits, resume_state, export.",
+  quickenrich_batch_employee_search: "Batch exact-person email lookup from persons/CSV/JSONL; optional phone lane; max_credits, resume_state, export.",
+  quickenrich_employee_search: "Single exact person lookup using linkedin_url or company_url + first_name + last_name.",
+  quickenrich_reverse_email: "Single reverse-email lookup.",
+  quickenrich_lookup_values: "Discover valid finder filter values: countries, industries, employee/revenue ranges, services.",
+};
+
+export const TOOL_DEFINITIONS = [
+  {
+    name: "quickenrich_auth_status",
+    description: "Check Quick Enrich MCP auth readiness without returning the API key. Env vars override local config.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "quickenrich_agent_graph",
+    description: "Return a compact capability map for the Quick Enrich MCP server, including endpoint rate limits and credit notes.",
+    inputSchema: { type: "object", properties: { response: responseSchema() }, required: [] },
+  },
+  {
+    name: "quickenrich_natural_language",
+    description: "Plan, and optionally execute, a Quick Enrich action from natural language. Use execute=false to inspect the plan before spending requests.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        request: { type: "string", description: "Plain-English request, e.g. 'pull founder leads for example.com and sample.com'." },
+        execute: { type: "boolean", description: "If true, execute the planned MCP tool. Default false.", default: false },
+        response: responseSchema(),
+      },
+      required: ["request"],
+    },
+  },
+  {
+    name: "quickenrich_employee_search",
+    description: "Find an exact person record and verified email using linkedin_url or company_url + first_name + last_name. Quick Enrich docs: GET /api/employees/search.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        linkedin_url: { type: "string" },
+        company_url: { type: "string" },
+        first_name: { type: "string" },
+        last_name: { type: "string" },
+        include_raw: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_phone_search",
+    description: "Look up a person's phone using linkedin_url or company_url + first_name + last_name. Quick Enrich docs: GET /api/employees/phone-search.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        linkedin_url: { type: "string" },
+        company_url: { type: "string" },
+        first_name: { type: "string" },
+        last_name: { type: "string" },
+        include_raw: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_reverse_email",
+    description: "Reverse lookup one exact email and return the best matching employee record. Quick Enrich docs: GET /api/employees/email-search.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: { type: "string", description: "Email address to look up." },
+        include_raw: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: ["email"],
+    },
+  },
+  {
+    name: "quickenrich_batch_reverse_email",
+    description: "Batch reverse-email lookup with dedupe, credit budget guard, endpoint throttling, compact output, and CSV/JSONL export.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        emails: { type: "array", items: { type: "string" } },
+        input_csv: { type: "string", description: "CSV text with an email column." },
+        input_jsonl: { type: "string", description: "JSONL text with email fields." },
+        input_file: { type: "string", description: "Local CSV/JSONL file path or file:// URL. Keeps large batches out of agent context." },
+        concurrency: { type: "integer", default: 8 },
+        requests_per_minute: { type: "integer", default: RATE_LIMITS.reverse_email },
+        burst_size: { type: "integer", default: 1 },
+        throttle_scope: { type: "string", enum: ["process", "shared"], default: "process" },
+        max_credits: { type: "integer", description: "Stop starting new paid lookups after this many credits are used." },
+        resume_state: { type: "object", description: "Prior batch state with completed/failed keys to skip already processed emails." },
+        resume_file: { type: "string", description: "Local JSON resume-state file to read/update after every row." },
+        output_file: { type: "string", description: "Local CSV/JSONL output file for results. Format inferred from extension unless export_format is set." },
+        export_format: { type: "string", enum: ["none", "jsonl", "csv"], default: "none" },
+        projection: projectionSchema(),
+        cache_mode: cacheModeSchema(),
+        credit_ledger: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_batch_employee_search",
+    description: "Batch exact-person email lookup using linkedin_url or company_url + first_name + last_name. Supports phone enrichment, credit guard, throttling, CSV/JSONL inputs, and CSV/JSONL export.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        persons: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              linkedin_url: { type: "string" },
+              company_url: { type: "string" },
+              first_name: { type: "string" },
+              last_name: { type: "string" },
+            },
+          },
+        },
+        input_csv: { type: "string", description: "CSV text with linkedin_url or company_url, first_name, last_name columns." },
+        input_jsonl: { type: "string", description: "JSONL text with exact-person lookup fields." },
+        input_file: { type: "string", description: "Local CSV/JSONL file path or file:// URL." },
+        include_phone: { type: "boolean", default: false },
+        concurrency: { type: "integer", default: 8 },
+        requests_per_minute: { type: "integer", default: RATE_LIMITS.employee_search },
+        phone_requests_per_minute: { type: "integer", default: RATE_LIMITS.phone_search },
+        burst_size: { type: "integer", default: 1 },
+        throttle_scope: { type: "string", enum: ["process", "shared"], default: "process" },
+        max_credits: { type: "integer", description: "Stop starting new paid lookups after this many credits are used." },
+        resume_state: { type: "object", description: "Prior batch state with completed/failed keys to skip already processed exact-person lookups." },
+        resume_file: { type: "string", description: "Local JSON resume-state file to read/update after every row." },
+        output_file: { type: "string", description: "Local CSV/JSONL output file for results." },
+        export_format: { type: "string", enum: ["none", "jsonl", "csv"], default: "none" },
+        projection: projectionSchema(),
+        cache_mode: cacheModeSchema(),
+        credit_ledger: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_domain_search",
+    description: "Pull contacts by company_url/domain and optional title. Paginates up to 20 contacts/page. Quick Enrich docs: GET /api/employees/dataset-search.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        company_url: { type: "string", description: "Company URL or domain." },
+        title: { type: "string", description: "Optional title filter, e.g. Founder or CEO." },
+        has_email: { type: "boolean", description: "If true, restrict results to contacts with an email signal." },
+        page: { type: "integer", default: 1 },
+        per_page: { type: "integer", default: 20 },
+        include_raw: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: ["company_url"],
+    },
+  },
+  {
+    name: "quickenrich_contact_finder",
+    description: "Discovery search across contact/company filters. Does not return email/phone values, only has_email/has_phone flags. Quick Enrich docs: POST /api/employees/contact-finder.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        body: { type: "object", description: "Raw Quick Enrich contact-finder body." },
+        filters: { type: "object", description: "Typed include/exclude filters for company_name, city, country_code, industry_linkedin, number_of_employees, revenue, title, and locality." },
+        has_email: { type: "boolean" },
+        has_phone: { type: "boolean" },
+        validate_filters: { type: "boolean", default: false },
+        page: { type: "integer", default: 1 },
+        per_page: { type: "integer", default: 10 },
+        include_raw: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_company_finder",
+    description: "Search companies by firmographic and text filters. Quick Enrich docs: POST /api/companies/company-finder.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        body: { type: "object", description: "Raw Quick Enrich company-finder body." },
+        filters: { type: "object", description: "Typed include/exclude filters for home_page_text, bio_li, services, industry, number_of_employees, revenue, country_code, city, and company_name." },
+        company_url: { type: "string", description: "Single domain or URL; no include/exclude wrapper." },
+        validate_filters: { type: "boolean", default: false },
+        page: { type: "integer", default: 1 },
+        per_page: { type: "integer", default: 10 },
+        include_raw: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_batch_pull_leads",
+    description: "Batch pull leads from company domains using domain search, contact finder, or company finder. Supports CSV/JSONL inputs, dry_run request planning, concurrency, dedupe, compact output, and optional contact enrichment.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mode: { type: "string", enum: ["domain_search", "contact_finder", "company_finder"], default: "domain_search" },
+        companies: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              company_url: { type: "string" },
+              domain: { type: "string" },
+              company_name: { type: "string" },
+              title: { type: "string" },
+            },
+          },
+        },
+        body: { type: "object", description: "Finder body for contact_finder or company_finder mode." },
+        input_csv: { type: "string", description: "CSV text with company_url/domain/url and optional title columns for domain_search mode." },
+        input_jsonl: { type: "string", description: "JSONL text with company_url/domain/url and optional title fields for domain_search mode." },
+        input_file: { type: "string", description: "Local CSV/JSONL file path or file:// URL." },
+        title: { type: "string", description: "Default title filter for domain_search mode." },
+        has_email: { type: "boolean", description: "Domain-search filter: only return contacts with an email signal when true." },
+        has_phone: { type: "boolean", description: "Contact Finder filter: only return contacts with a phone signal when true." },
+        per_company_limit: { type: "integer", default: 20 },
+        pages_per_company: { type: "integer", default: 1 },
+        per_page: { type: "integer", default: 20 },
+        concurrency: { type: "integer", default: 8 },
+        requests_per_minute: { type: "integer", default: RATE_LIMITS.domain_search, description: "Domain-search request start ceiling. Default is Quick Enrich's published 300/min. Set higher only with provider approval." },
+        burst_size: { type: "integer", default: 1, description: "Initial request burst before pacing. Default 1 is strict; raise only when the account/provider allows burst traffic." },
+        throttle_scope: { type: "string", enum: ["process", "shared"], default: "process" },
+        filters: { type: "object", description: "Typed Contact/Company Finder include/exclude filters. Arrays become {include:[...],exclude:[]}." },
+        max_results: { type: "integer", description: "Maximum records to collect for finder modes." },
+        max_credits: { type: "integer", description: "Stop starting new paid requests after this many credits are used." },
+        validate_filters: { type: "boolean", default: false },
+        resume_state: { type: "object", description: "Prior batch state with completed/failed keys for resumable large runs." },
+        resume_file: { type: "string", description: "Local JSON resume-state file to read/update after every page/company." },
+        output_file: { type: "string", description: "Local CSV/JSONL output file for results." },
+        export_format: { type: "string", enum: ["none", "jsonl", "csv"], default: "none" },
+        projection: projectionSchema(),
+        cache_mode: cacheModeSchema(),
+        credit_ledger: { type: "boolean", default: false },
+        enrich_contacts: { type: "boolean", default: false },
+        include_phone_enrichment: { type: "boolean", default: false },
+        max_enrichments: { type: "integer", default: 50 },
+        dry_run: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_pipeline",
+    description: "Run native Quick Enrich workflows end to end. Starts with company discovery, dedupes domains, pulls contacts, writes durable output/resume files, and returns compact projected rows.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mode: { type: "string", enum: ["company_finder_to_domain_search"], default: "company_finder_to_domain_search" },
+        body: { type: "object", description: "Raw Quick Enrich company-finder body for the first pipeline step." },
+        filters: { type: "object", description: "Typed Company Finder filters." },
+        max_companies: { type: "integer", default: 25 },
+        title: { type: "string", description: "Domain-search title filter for the second pipeline step." },
+        per_company_limit: { type: "integer", default: 20 },
+        pages_per_company: { type: "integer", default: 1 },
+        concurrency: { type: "integer", default: 8 },
+        requests_per_minute: { type: "integer", default: RATE_LIMITS.domain_search },
+        burst_size: { type: "integer", default: 1 },
+        throttle_scope: { type: "string", enum: ["process", "shared"], default: "process" },
+        max_credits: { type: "integer" },
+        output_file: { type: "string" },
+        resume_file: { type: "string" },
+        export_format: { type: "string", enum: ["none", "jsonl", "csv"], default: "none" },
+        projection: projectionSchema(),
+        cache_mode: cacheModeSchema(),
+        credit_ledger: { type: "boolean", default: false },
+        response: responseSchema(),
+      },
+      required: [],
+    },
+  },
+  {
+    name: "quickenrich_lookup_values",
+    description: "Read public Quick Enrich lookup values for validated finder fields: country codes, industries, employee ranges, revenue ranges, or company services.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lookup: { type: "string", enum: Object.keys(LOOKUP_PATHS) },
+        q: { type: "string", description: "Optional search query for company_services." },
+        response: responseSchema(),
+      },
+      required: ["lookup"],
+    },
+  },
+];
+
+export function responseSchema() {
+  return {
+    type: "object",
+    properties: {
+      mode: { type: "string", enum: ["compact", "full", "meta"], default: "compact" },
+      maxItems: { type: "integer", default: 25 },
+      maxKeys: { type: "integer", default: 80 },
+      maxDepth: { type: "integer", default: 5 },
+      maxStringChars: { type: "integer", default: 1200 },
+      maxOutputChars: { type: "integer", default: MAX_OUTPUT_CHARS },
+    },
+  };
+}
+
+export function projectionSchema() {
+  return { type: "string", enum: [...PROJECTION_MODES], default: "full" };
+}
+
+export function cacheModeSchema() {
+  return { type: "string", enum: [...CACHE_MODES], default: "off" };
+}
+
+export function toolMode() {
+  return String(process.env.QUICKENRICH_MCP_TOOL_MODE || "agent").toLowerCase();
+}
+
+export function selectTools(tools = TOOL_DEFINITIONS, mode = toolMode()) {
+  if (mode === "full") return tools;
+  const slim = (tool) => slimAgentToolDefinition(tool);
+  if (mode === "minimal") {
+    return tools.filter((tool) => [
+      "quickenrich_auth_status",
+      "quickenrich_agent_graph",
+      "quickenrich_natural_language",
+      "quickenrich_batch_pull_leads",
+    ].includes(tool.name)).map(slim);
+  }
+  return tools.filter((tool) => AGENT_TOOL_NAMES.has(tool.name)).map(slim);
+}
+
+function slimAgentToolDefinition(tool) {
+  return {
+    name: tool.name,
+    description: AGENT_TOOL_BRIEFS[tool.name] || tool.description,
+    inputSchema: slimAgentSchema(tool.inputSchema),
+  };
+}
+
+function slimAgentSchema(schema) {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) return schema.map(slimAgentSchema);
+  const out = {};
+  for (const key of ["type", "enum", "required"]) {
+    if (schema[key] !== undefined) out[key] = schema[key];
+  }
+  if (schema.items) out.items = slimAgentSchema(schema.items);
+  if (schema.properties) {
+    out.properties = {};
+    for (const [key, value] of Object.entries(schema.properties)) {
+      out.properties[key] = key === "response" ? { type: "object" } : slimAgentSchema(value);
+    }
+  }
+  return out;
+}
+
+export function defaultConfigPath() {
+  return process.env.QUICKENRICH_MCP_CONFIG || DEFAULT_CONFIG_PATH;
+}
+
+export function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw new Error(`Failed to read JSON config ${path}: ${error.message || error}`);
+  }
+}
+
+export function readConfig() {
+  const path = defaultConfigPath();
+  const config = readJsonFile(path) || {};
+  return { path, config };
+}
+
+export function writeToken(token, path = defaultConfigPath()) {
+  const value = String(token || "").trim();
+  if (!value) throw new Error("Quick Enrich API key is required.");
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify({ apiKey: value }, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return path;
+}
+
+export function removeToken(path = defaultConfigPath()) {
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // Removal is idempotent.
+  }
+  return path;
+}
+
+export function apiKey() {
+  const { config } = readConfig();
+  return (
+    process.env.QUICKENRICH_API_KEY ||
+    process.env.QUICKENRICH_TOKEN ||
+    config.apiKey ||
+    config.api_key ||
+    config.token ||
+    ""
+  ).trim();
+}
+
+export function apiBaseUrl() {
+  return (process.env.QUICKENRICH_API_BASE_URL || DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+}
+
+export function authStatus() {
+  const key = apiKey();
+  const { path } = readConfig();
+  return {
+    configured: Boolean(key),
+    source: process.env.QUICKENRICH_API_KEY
+      ? "QUICKENRICH_API_KEY"
+      : process.env.QUICKENRICH_TOKEN
+        ? "QUICKENRICH_TOKEN"
+        : key
+          ? path
+          : "not_configured",
+    apiBaseUrl: apiBaseUrl(),
+    docsUrl: DOCS_URL,
+    configPath: path,
+    server: {
+      name: process.env.QUICKENRICH_MCP_SERVER_NAME || "quick-enrich",
+      version: SERVER_VERSION,
+      toolPrefix: "quickenrich_*",
+    },
+  };
+}
+
+export class QuickEnrichClient {
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl || apiBaseUrl()).replace(/\/+$/, "");
+    this.fetchImpl = options.fetchImpl || null;
+    this.useFetchTransport = Boolean(this.fetchImpl) || USE_FETCH_TRANSPORT;
+    this.httpAgent = options.httpAgent || SHARED_HTTP_AGENT;
+    this.httpsAgent = options.httpsAgent || SHARED_HTTPS_AGENT;
+    this.timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS);
+    this.retryCount = positiveInteger(options.retryCount, DEFAULT_RETRY_COUNT);
+    this.retryBaseMs = positiveInteger(options.retryBaseMs, DEFAULT_RETRY_BASE_MS);
+    this.inflight = new Map();
+    this.throttleLimiters = new Map();
+  }
+
+  authHeader() {
+    const key = apiKey();
+    if (!key) {
+      const status = authStatus();
+      throw new Error(`Quick Enrich API key is not configured. Set QUICKENRICH_API_KEY or run quickenrich-token set. Config path: ${status.configPath}`);
+    }
+    return `Bearer ${key}`;
+  }
+
+  buildUrl(path, query = {}) {
+    return this.buildUrlTarget(path, query).toString();
+  }
+
+  buildUrlTarget(path, query = {}) {
+    if (!path || typeof path !== "string") throw new Error("path is required");
+    const base = new URL(this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`);
+    const target = /^https?:\/\//i.test(path) ? new URL(path) : new URL(path.replace(/^\/+/, ""), base);
+    if (target.origin !== base.origin) {
+      throw new Error(`Refusing to send Quick Enrich credentials outside ${base.origin}`);
+    }
+    for (const [key, value] of Object.entries(cleanObject(query))) {
+      if (Array.isArray(value)) {
+        for (const item of value) target.searchParams.append(key, String(item));
+      } else {
+        target.searchParams.set(key, String(value));
+      }
+    }
+    return target;
+  }
+
+  async request({ method = "GET", path, query, body, auth = true, endpoint = "request" }) {
+    const target = this.buildUrlTarget(path, query);
+    const url = target.toString();
+    const headers = {
+      Accept: "application/json",
+      "User-Agent": "quickenrich-mcp/0.1.0",
+    };
+    if (auth) headers.Authorization = this.authHeader();
+    let payload;
+    if (body !== undefined) {
+      payload = JSON.stringify(body);
+      headers["Content-Type"] = "application/json";
+    }
+
+    const requestKey = `${method.toUpperCase()} ${url} ${payload || ""} auth:${auth ? "1" : "0"}`;
+    if (this.inflight.has(requestKey)) return this.inflight.get(requestKey);
+    const pending = this._requestOnce({ method, path, endpoint, url, target, headers, payload, requestKey });
+    this.inflight.set(requestKey, pending);
+    try {
+      return await pending;
+    } finally {
+      this.inflight.delete(requestKey);
+    }
+  }
+
+  async _requestOnce({ method, path, endpoint, url, target, headers, payload }) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.retryCount; attempt += 1) {
+      let timeout;
+      try {
+        let response;
+        if (this.useFetchTransport) {
+          const controller = new AbortController();
+          timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+          response = await requestJsonFetch({
+            fetchImpl: this.fetchImpl || globalThis.fetch,
+            url,
+            method,
+            headers,
+            payload,
+            signal: controller.signal,
+          });
+        } else {
+          response = await requestJsonNative({
+            target,
+            method,
+            headers,
+            payload,
+            timeoutMs: this.timeoutMs,
+            httpAgent: this.httpAgent,
+            httpsAgent: this.httpsAgent,
+          });
+        }
+        if (timeout) clearTimeout(timeout);
+        if (response.ok) {
+          return {
+            ok: true,
+            endpoint,
+            status: response.status,
+            data: response.data,
+            rateLimit: rateLimitHeaders(response.headers),
+          };
+        }
+        const retryAfter = Number(headerValue(response.headers, "retry-after") || 0);
+        if ((response.status === 429 || response.status >= 500) && attempt < this.retryCount) {
+          await sleep(retryAfter ? retryAfter * 1000 : this.retryBaseMs * 2 ** attempt);
+          continue;
+        }
+        const error = new Error(`Quick Enrich ${method} ${path} failed with HTTP ${response.status}`);
+        error.result = { status: response.status, endpoint, data: response.data, rateLimit: rateLimitHeaders(response.headers) };
+        throw error;
+      } catch (error) {
+        if (timeout) clearTimeout(timeout);
+        lastError = error;
+        if (attempt < this.retryCount && (error?.name === "AbortError" || error?.code === "ECONNRESET")) {
+          await sleep(this.retryBaseMs * 2 ** attempt);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError || new Error(`Quick Enrich ${method} ${path} failed`);
+  }
+
+  throttleLimiter(options) {
+    const key = `${options.endpoint}:${options.requestsPerMinute}:${options.burstSize}`;
+    if (!this.throttleLimiters.has(key)) {
+      this.throttleLimiters.set(key, createTokenBucketLimiter(options));
+    }
+    return this.throttleLimiters.get(key);
+  }
+}
+
+export function createClient(options = {}) {
+  return new QuickEnrichClient(options);
+}
+
+export async function callQuickEnrichTool(name, args = {}, client = createClient()) {
+  const source = args && typeof args === "object" ? args : {};
+  let result;
+  if (name === "quickenrich_auth_status") result = authStatus();
+  else if (name === "quickenrich_agent_graph") result = agentGraph();
+  else if (name === "quickenrich_natural_language") result = await naturalLanguage(source, client);
+  else if (name === "quickenrich_pipeline") result = await quickenrichPipeline(source, client);
+  else if (name === "quickenrich_employee_search") result = await employeeSearch(source, client);
+  else if (name === "quickenrich_phone_search") result = await phoneSearch(source, client);
+  else if (name === "quickenrich_reverse_email") result = await reverseEmail(source, client);
+  else if (name === "quickenrich_batch_reverse_email") result = await batchReverseEmail(source, client);
+  else if (name === "quickenrich_batch_employee_search") result = await batchEmployeeSearch(source, client);
+  else if (name === "quickenrich_domain_search") result = await domainSearch(source, client);
+  else if (name === "quickenrich_contact_finder") result = await contactFinder(source, client);
+  else if (name === "quickenrich_company_finder") result = await companyFinder(source, client);
+  else if (name === "quickenrich_batch_pull_leads") result = await batchPullLeads(source, client);
+  else if (name === "quickenrich_lookup_values") result = await lookupValues(source, client);
+  else throw new Error(`Unknown Quick Enrich tool: ${name}`);
+  return compactToolPayload(result, source.response);
+}
+
+export function agentGraph() {
+  return {
+    ok: true,
+    server: authStatus().server,
+    docsUrl: DOCS_URL,
+    auth: {
+      env: ["QUICKENRICH_API_KEY", "QUICKENRICH_TOKEN"],
+      configPath: defaultConfigPath(),
+      header: "Authorization: Bearer <api-key>",
+    },
+    defaultTools: [...AGENT_TOOL_NAMES],
+    surfaceModes: {
+      agent: "Default: 9 compact tools for normal agents, including lookup discovery.",
+      minimal: "Auth, graph, natural-language planner, and batch pull only.",
+      full: "All documented Quick Enrich endpoints and verbose schemas.",
+    },
+    envelopePolicy: {
+      default: { mode: "compact", maxOutputChars: MAX_OUTPUT_CHARS, maxItems: 12, maxDepth: 4, maxStringChars: 240 },
+      planning: { response: { mode: "meta" }, useWhen: "Need counts/shape only or large batches." },
+      export: "Use output_file for large jobs, export_format for small inline handoff, projection to shrink row fields.",
+    },
+    bulkIO: {
+      input_file: "Local .csv/.jsonl path or file:// URL on batch tools; avoids pasting rows into agent context.",
+      output_file: "Local .jsonl/.csv artifact for records; response returns path/count/bytes.",
+      resume_file: "Local JSON checkpoint merged with resume_state and updated after each row/page.",
+    },
+    projections: {
+      modes: ["full", "people", "companies", "emails", "phones", "ids"],
+      default: "full for compatibility; use emails/people/companies/ids for agent-token savings.",
+    },
+    cacheLedger: {
+      toolArgs: ["cache_mode", "credit_ledger"],
+      cacheModes: ["off", "read", "write", "readwrite", "refresh", "cache_only"],
+      paths: {
+        cacheDir: process.env.QUICKENRICH_MCP_CACHE_DIR || join(DEFAULT_DATA_DIR, "cache"),
+        ledgerPath: process.env.QUICKENRICH_MCP_LEDGER_PATH || join(DEFAULT_DATA_DIR, "credits.jsonl"),
+      },
+    },
+    evalBudgets: { toolsListBytes: 8_000, graphCompactBytes: 8_000, graphMetaBytes: 1_600 },
+    inputHints: {
+      domain_csv: "company_url/domain/url,title; use input_file/input_csv on batch_pull_leads mode=domain_search.",
+      reverse_csv: "email/email_address/value; use input_file/input_csv on batch_reverse_email.",
+      exact_jsonl: "company_url/domain/url + first_name + last_name, or linkedin_url; use input_file/input_jsonl.",
+      finder_resume: "Pass prior resumeState unchanged with identical mode+filters; stale nextPage is ignored when fingerprint changes.",
+    },
+    budgetMath: {
+      domain_search: "Estimate domains * pages_per_company; duplicates coalesce before spend.",
+      reverse_email: "Reserve 1 per unique valid email; charged only on match.",
+      exact_email_phone: "Reserve up to 1 for email plus 1 more for phone per found person when include_phone=true.",
+      company_finder: "Reserve roughly max_results; credit-limited per_page shrinks to remaining budget.",
+      contact_finder: "Discovery search is free; enrichment follow-up uses employee/phone budgets.",
+    },
+    lookupHints: {
+      tool: "quickenrich_lookup_values",
+      fields: {
+        country_code: "country_codes",
+        industry_linkedin: "industries",
+        industry: "industries",
+        number_of_employees: "employee_ranges",
+        revenue: "revenue_ranges",
+        services: "company_services",
+      },
+    },
+    rateLimitsPerMinute: RATE_LIMITS,
+    endpointCoverage: [
+      { endpoint: "employee_search", method: "GET", path: "/api/employees/search", tool: "quickenrich_employee_search", batchTool: "quickenrich_batch_employee_search", auth: true },
+      { endpoint: "phone_search", method: "GET", path: "/api/employees/phone-search", tool: "quickenrich_phone_search", batchTool: "quickenrich_batch_employee_search", auth: true },
+      { endpoint: "reverse_email", method: "GET", path: "/api/employees/email-search", tool: "quickenrich_reverse_email", batchTool: "quickenrich_batch_reverse_email", auth: true },
+      { endpoint: "domain_search", method: "GET", path: "/api/employees/dataset-search", tool: "quickenrich_domain_search", batchTool: "quickenrich_batch_pull_leads", auth: true },
+      { endpoint: "contact_finder", method: "POST", path: "/api/employees/contact-finder", tool: "quickenrich_contact_finder", batchTool: "quickenrich_batch_pull_leads", auth: true },
+      { endpoint: "company_finder", method: "POST", path: "/api/companies/company-finder", tool: "quickenrich_company_finder", batchTool: "quickenrich_batch_pull_leads", auth: true },
+      { endpoint: "lookup_values", method: "GET", path: "/api/lookups/*", tool: "quickenrich_lookup_values", auth: false },
+    ],
+    agentRouting: [
+      { intent: "company filters to contact rows", tool: "quickenrich_pipeline", args: ["mode=company_finder_to_domain_search", "filters/body", "max_companies", "title?", "output_file?", "projection?"], why: ["native chaining", "dedupe", "durable artifacts"] },
+      { intent: "domains to leads", tool: "quickenrich_batch_pull_leads", args: ["mode=domain_search", "companies or input_csv/input_jsonl", "title?", "max_credits?", "resume_state?"], why: ["dedupe", "300/min pacing", "export", "compact/meta"] },
+      { intent: "contact discovery filters", tool: "quickenrich_batch_pull_leads", args: ["mode=contact_finder", "filters/body", "max_results", "resume_state?"], why: ["pagination", "free discovery", "optional enrichment"] },
+      { intent: "company discovery filters", tool: "quickenrich_batch_pull_leads", args: ["mode=company_finder", "filters/body", "max_results", "max_credits?", "resume_state?"], why: ["pagination", "company-shaped output", "credit guard"] },
+      { intent: "many reverse emails", tool: "quickenrich_batch_reverse_email", args: ["emails or input_csv/input_jsonl", "max_credits?", "resume_state?", "export_format?"], why: ["dedupe", "invalid email preflight"] },
+      { intent: "many exact people", tool: "quickenrich_batch_employee_search", args: ["persons or input_csv/input_jsonl", "include_phone?", "max_credits?", "resume_state?", "export_format?"], why: ["email+phone lanes", "endpoint throttles"] },
+      { intent: "single exact lookup", tool: "quickenrich_batch_employee_search", args: ["persons:[{linkedin_url or company_url+first_name+last_name}]"], why: ["default surface", "same endpoint", "resume/cache ready"] },
+    ],
+    coldStartRecipes: [
+      { ask: "I have a file/CSV/JSONL", use: "Set input_file on the matching batch tool; avoid pasting file rows into natural_language." },
+      { ask: "Large run", use: "Set max_credits, output_file, resume_file, projection, response:{mode:'meta'}." },
+      { ask: "Ambiguous request", use: "Call quickenrich_natural_language with execute=false; execute=true only when plan.requires is empty." },
+    ],
+    batchThrottleDefaults: {
+      domain_search: throttleOptions({}, "domain_search"),
+      contact_finder: throttleOptions({}, "contact_finder"),
+      company_finder: throttleOptions({}, "company_finder"),
+      employee_search: throttleOptions({}, "employee_search"),
+      phone_search: throttleOptions({}, "phone_search"),
+      reverse_email: throttleOptions({}, "reverse_email"),
+    },
+    creditNotes: {
+      employee_search: "Credit behavior follows Quick Enrich's Email Search endpoint.",
+      phone_search: "One credit is deducted only when a phone number is returned.",
+      reverse_email: "One credit is deducted only when a match is found and returned.",
+      domain_search: "If title is provided, credits are per employee with email/phone on the current page; if omitted, a flat credit is charged when the page has results.",
+      contact_finder: "Search is free and discovery-only; responses omit email/phone values.",
+      company_finder: "One credit is deducted per company returned unless account plan waives it.",
+    },
+  };
+}
+
+export async function employeeSearch(args, client) {
+  requirePersonLocator(args);
+  const response = await client.request({
+    endpoint: "employee_search",
+    path: "/api/employees/search",
+    query: {
+      linkedin_url: args.linkedin_url,
+      company_url: args.company_url,
+      first_name: args.first_name,
+      last_name: args.last_name,
+    },
+  });
+  return normalizedSingle("employee_search", response, args.include_raw);
+}
+
+export async function phoneSearch(args, client) {
+  requirePersonLocator(args);
+  const response = await client.request({
+    endpoint: "phone_search",
+    path: "/api/employees/phone-search",
+    query: {
+      linkedin_url: args.linkedin_url,
+      company_url: args.company_url,
+      first_name: args.first_name,
+      last_name: args.last_name,
+    },
+  });
+  return normalizedSingle("phone_search", response, args.include_raw);
+}
+
+export async function reverseEmail(args, client) {
+  const email = String(args.email || "").trim();
+  const validationError = emailValidationError(email);
+  if (validationError) throw new Error(validationError);
+  const response = await client.request({
+    endpoint: "reverse_email",
+    path: "/api/employees/email-search",
+    query: { email },
+  });
+  return normalizedSingle("reverse_email", response, args.include_raw);
+}
+
+export async function domainSearch(args, client) {
+  const companyUrl = args.company_url || args.domain;
+  if (!companyUrl) throw new Error("company_url is required.");
+  const response = await client.request({
+    endpoint: "domain_search",
+    path: "/api/employees/dataset-search",
+    query: {
+      company_url: companyUrl,
+      title: args.title,
+      has_email: booleanQuery(args.has_email),
+      page: clampInt(args.page, 1, 10_000, 1),
+      per_page: clampInt(args.per_page, 1, 20, 20),
+    },
+  });
+  return normalizedList("domain_search", response, args.include_raw);
+}
+
+export async function contactFinder(args, client) {
+  const body = contactFinderBody(args);
+  const validation = args.validate_filters ? await validateFinderFilters("contact_finder", args, client) : undefined;
+  if (validation && !validation.ok) {
+    return {
+      ok: false,
+      endpoint: "contact_finder",
+      count: 0,
+      records: [],
+      creditsUsed: 0,
+      validation,
+      rateLimitPerMinute: RATE_LIMITS.contact_finder,
+    };
+  }
+  const response = await client.request({
+    endpoint: "contact_finder",
+    method: "POST",
+    path: "/api/employees/contact-finder",
+    body,
+  });
+  return {
+    ...normalizedList("contact_finder", response, args.include_raw),
+    validation,
+  };
+}
+
+export async function companyFinder(args, client) {
+  const body = companyFinderBody(args);
+  const validation = args.validate_filters ? await validateFinderFilters("company_finder", args, client) : undefined;
+  if (validation && !validation.ok) {
+    return {
+      ok: false,
+      endpoint: "company_finder",
+      count: 0,
+      records: [],
+      creditsUsed: 0,
+      validation,
+      rateLimitPerMinute: RATE_LIMITS.company_finder,
+    };
+  }
+  const response = await client.request({
+    endpoint: "company_finder",
+    method: "POST",
+    path: "/api/companies/company-finder",
+    body,
+  });
+  return {
+    ...normalizedList("company_finder", response, args.include_raw),
+    validation,
+  };
+}
+
+export async function lookupValues(args, client) {
+  const lookup = args.lookup;
+  const path = LOOKUP_PATHS[lookup];
+  if (!path) throw new Error(`Unknown lookup: ${lookup}`);
+  const response = await client.request({
+    endpoint: "lookup_values",
+    path,
+    query: lookup === "company_services" ? { q: args.q } : {},
+    auth: false,
+  });
+  return {
+    ok: true,
+    endpoint: "lookup_values",
+    lookup,
+    data: response.data,
+    rateLimit: response.rateLimit,
+  };
+}
+
+export async function quickenrichPipeline(args, client) {
+  args = prepareBulkArgs(args);
+  const mode = args.mode || "company_finder_to_domain_search";
+  if (mode !== "company_finder_to_domain_search") throw new Error(`Unknown pipeline mode: ${mode}`);
+  const maxCompanies = clampInt(args.max_companies, 1, 1_000, 25);
+  const startedAt = Date.now();
+  const companyStep = await batchPullLeads({
+    ...args,
+    mode: "company_finder",
+    max_results: maxCompanies,
+    per_page: clampInt(args.per_page, 1, 100, Math.min(100, maxCompanies)),
+    pages_per_company: args.company_pages || args.pages_per_company || 1,
+    output_file: undefined,
+    resume_file: undefined,
+    export_format: "none",
+    projection: "full",
+    response: { mode: "full", maxOutputChars: 5_000_000 },
+  }, client);
+  const companies = Array.isArray(companyStep.companies) ? companyStep.companies.slice(0, maxCompanies) : [];
+  const domainInputs = companies
+    .map((company) => ({
+      company_url: company.domain || company.url || company.email_domain || company.final_email_domain,
+      company_name: company.company_name,
+      title: args.title,
+    }))
+    .filter((company) => company.company_url);
+  const pipelineMaxCredits = Number(args.max_credits);
+  const remainingPipelineCredits = Number.isFinite(pipelineMaxCredits) && pipelineMaxCredits >= 0
+    ? Math.max(0, Math.floor(pipelineMaxCredits) - Number(companyStep.creditsUsed || 0))
+    : undefined;
+  const domainStep = domainInputs.length
+    ? await batchPullLeads({
+      ...args,
+      mode: "domain_search",
+      companies: domainInputs,
+      input_file: undefined,
+      input_csv: undefined,
+      input_jsonl: undefined,
+      pages_per_company: args.domain_pages || 1,
+      per_company_limit: args.per_company_limit,
+      title: args.title,
+      max_credits: remainingPipelineCredits,
+      output_file: args.output_file,
+      resume_file: args.resume_file,
+      export_format: args.export_format,
+      projection: args.projection,
+      response: { mode: "full", maxOutputChars: 5_000_000 },
+    }, client)
+    : { ok: true, requestCount: 0, creditsUsed: 0, leadCount: 0, leads: [], errors: [] };
+  const result = {
+    ok: Boolean(companyStep.ok && domainStep.ok),
+    mode,
+    steps: [
+      {
+        tool: "quickenrich_batch_pull_leads",
+        mode: "company_finder",
+        requestCount: companyStep.requestCount,
+        creditsUsed: companyStep.creditsUsed,
+        companyCount: companyStep.companyCount,
+      },
+      {
+        tool: "quickenrich_batch_pull_leads",
+        mode: "domain_search",
+        requestCount: domainStep.requestCount,
+        creditsUsed: domainStep.creditsUsed,
+        leadCount: domainStep.leadCount,
+      },
+    ],
+    requestCount: (companyStep.requestCount || 0) + (domainStep.requestCount || 0),
+    creditsUsed: (companyStep.creditsUsed || 0) + (domainStep.creditsUsed || 0),
+    remainingCredits: minDefined([companyStep.remainingCredits, domainStep.remainingCredits]),
+    companyCount: companies.length,
+    companies,
+    leadCount: domainStep.leadCount || 0,
+    leads: domainStep.leads || [],
+    errors: [...(companyStep.errors || []), ...(domainStep.errors || [])],
+    output: domainStep.output,
+    resume: domainStep.resume,
+    ledger: args.credit_ledger ? appendCreditLedger(args, { ...domainStep, mode }) : domainStep.ledger,
+    durationMs: Date.now() - startedAt,
+  };
+  if (projectionMode(args) === "companies") {
+    result.companies = projectRows(companies, "companies", "company_finder");
+  }
+  return result;
+}
+
+export async function batchPullLeads(args, client) {
+  args = prepareBulkArgs(args);
+  const mode = args.mode || "domain_search";
+  const perPage = mode === "domain_search" ? clampInt(args.per_page, 1, 20, 20) : clampInt(args.per_page, 1, 100, 10);
+  const pagesPerCompany = clampInt(args.pages_per_company, 1, 10, 1);
+  const perCompanyLimit = clampInt(args.per_company_limit, 1, 200, 20);
+  const concurrency = clampInt(args.concurrency, 1, MAX_BATCH_CONCURRENCY, 8);
+  const maxEnrichments = clampInt(args.max_enrichments, 0, 500, 50);
+  const maxResults = clampInt(args.max_results, 1, 10_000, perPage);
+  const exportFormat = exportFormatOption(args.export_format);
+  const creditBudget = createCreditBudget(args.max_credits);
+
+  if (mode === "domain_search") {
+    const companies = normalizeCompanyInputs([
+      ...(Array.isArray(args.companies) ? args.companies : []),
+      ...recordsFromTextInputs(args),
+    ]);
+    const uniqueCompanies = uniqueDomainSearchCompanies(companies, args.title);
+    const resume = createResumeTracker(args.resume_state, uniqueCompanies, domainSearchBatchKey, resumeTrackerOptions(args));
+    const plannedRequests = resume.items.length * pagesPerCompany;
+    const throttle = requestThrottle(client, args, "domain_search");
+    const domainCreditEstimate = 1;
+    if (args.dry_run) {
+      return batchPlan({ mode, companies: resume.items, inputCompanyCount: companies.length, plannedRequests, concurrency, perPage, pagesPerCompany, perCompanyLimit, throttle: throttle.summary(), creditBudget: creditBudget.summary(), resumeState: resume.summary() });
+    }
+    const startedAt = Date.now();
+    const pulled = await withConcurrency(resume.items, concurrency, async (company) => {
+      const entry = await pullCompanyDomainLeads(company, {
+        perPage,
+        pagesPerCompany,
+        perCompanyLimit,
+        title: company.title || args.title,
+        hasEmail: args.has_email,
+        creditEstimate: domainCreditEstimate,
+        throttle,
+        creditBudget,
+      }, client);
+      if (entry.errors?.length) resume.fail(company);
+      else if (entry.requestCount > 0) resume.complete(company);
+      return entry;
+    });
+    const leads = dedupeLeads(pulled.flatMap((entry) => entry.leads));
+    const errors = pulled.flatMap((entry) => entry.errors);
+    const enriched = args.enrich_contacts
+      ? await enrichLeads(leads, { includePhone: Boolean(args.include_phone_enrichment), maxEnrichments, concurrency, creditBudget }, client)
+      : { leads, enrichmentRequests: 0, creditsUsed: 0, remainingCredits: undefined, errors: [] };
+    const outputLeads = enriched.leads;
+    const result = {
+      ok: errors.length === 0 && enriched.errors.length === 0,
+      mode,
+      requestCount: pulled.reduce((sum, entry) => sum + entry.requestCount, 0) + enriched.enrichmentRequests,
+      inputCompanyCount: companies.length,
+      companyCount: uniqueCompanies.length,
+      coalescedCompanyCount: companies.length - uniqueCompanies.length,
+      creditsUsed: pulled.reduce((sum, entry) => sum + entry.creditsUsed, 0) + enriched.creditsUsed,
+      remainingCredits: minDefined(pulled.map((entry) => entry.remainingCredits).concat(enriched.remainingCredits)),
+      leadCount: outputLeads.length,
+      leads: outputLeads,
+      errors: [...errors, ...enriched.errors],
+      durationMs: Date.now() - startedAt,
+      rateLimitPerMinute: RATE_LIMITS.domain_search,
+      throttle: throttle.summary(),
+      creditBudget: creditBudget.summary(),
+      resumeState: resume.summary(),
+      export: formatExport(projectRows(outputLeads, projectionMode(args), "domain_search"), exportFormat),
+      creditNotes: agentGraph().creditNotes.domain_search,
+    };
+    return finalizeRowsResult(result, args, "leads", "domain_search", outputLeads);
+  }
+
+  if (mode === "contact_finder") {
+    if (args.dry_run) return batchPlan({ mode, plannedRequests: 1, concurrency: 1, perPage });
+    const validation = args.validate_filters ? await validateFinderFilters("contact_finder", args, client) : undefined;
+    if (validation && !validation.ok) {
+      return {
+        ok: false,
+        mode,
+        requestCount: 0,
+        creditsUsed: 0,
+        leadCount: 0,
+        leads: [],
+        errors: [],
+        validation,
+        creditBudget: creditBudget.summary(),
+      };
+    }
+    const result = await pagedFinder("contact_finder", args, { perPage, maxResults, maxPages: pagesPerCompany, concurrency, creditBudget, creditEstimate: 0 }, client);
+    const leads = dedupeLeads(result.records || []);
+    const enriched = args.enrich_contacts
+      ? await enrichLeads(leads, { includePhone: Boolean(args.include_phone_enrichment), maxEnrichments, concurrency, creditBudget }, client)
+      : { leads, enrichmentRequests: 0, creditsUsed: 0, remainingCredits: undefined, errors: [] };
+    const outputLeads = enriched.leads;
+    const resultOut = {
+      ok: (result.errors || []).length === 0 && enriched.errors.length === 0,
+      mode,
+      requestCount: result.requestCount + enriched.enrichmentRequests,
+      creditsUsed: (result.creditsUsed || 0) + enriched.creditsUsed,
+      remainingCredits: minDefined([result.remainingCredits, enriched.remainingCredits]),
+      leadCount: outputLeads.length,
+      leads: outputLeads,
+      errors: [...(result.errors || []), ...enriched.errors],
+      rateLimitPerMinute: RATE_LIMITS.contact_finder,
+      throttle: result.throttle,
+      creditBudget: creditBudget.summary(),
+      resumeState: result.resumeState,
+      validation,
+      export: formatExport(projectRows(outputLeads, projectionMode(args), "contact_finder"), exportFormat),
+      creditNotes: agentGraph().creditNotes.contact_finder,
+    };
+    return finalizeRowsResult(resultOut, args, "leads", "contact_finder", outputLeads);
+  }
+
+  if (mode === "company_finder") {
+    if (args.dry_run) return batchPlan({ mode, plannedRequests: 1, concurrency: 1, perPage });
+    const validation = args.validate_filters ? await validateFinderFilters("company_finder", args, client) : undefined;
+    if (validation && !validation.ok) {
+      return {
+        ok: false,
+        mode,
+        requestCount: 0,
+        creditsUsed: 0,
+        companyCount: 0,
+        companies: [],
+        errors: [],
+        validation,
+        creditBudget: creditBudget.summary(),
+      };
+    }
+    const result = await pagedFinder("company_finder", args, { perPage, maxResults, maxPages: pagesPerCompany, concurrency, creditBudget, creditEstimate: Math.max(1, perPage) }, client);
+    const companies = result.records || [];
+    const resultOut = {
+      ok: (result.errors || []).length === 0,
+      mode,
+      requestCount: result.requestCount,
+      creditsUsed: result.creditsUsed,
+      remainingCredits: result.remainingCredits,
+      companyCount: companies.length,
+      companies,
+      errors: result.errors || [],
+      throttle: result.throttle,
+      creditBudget: creditBudget.summary(),
+      resumeState: result.resumeState,
+      validation,
+      export: formatExport(projectRows(companies, projectionMode(args), "company_finder"), exportFormat),
+      rateLimitPerMinute: RATE_LIMITS.company_finder,
+      creditNotes: agentGraph().creditNotes.company_finder,
+    };
+    return finalizeRowsResult(resultOut, args, "companies", "company_finder", companies);
+  }
+
+  throw new Error(`Unknown batch mode: ${mode}`);
+}
+
+export async function batchReverseEmail(args, client) {
+  args = prepareBulkArgs(args);
+  const emails = uniqueStrings([
+    ...(Array.isArray(args.emails) ? args.emails : []),
+    ...recordsFromTextInputs(args).map((row) => row.email || row.email_address || row.value),
+  ].filter(Boolean));
+  if (!emails.length) throw new Error("emails or input_csv/input_jsonl must include at least one email.");
+  const concurrency = clampInt(args.concurrency, 1, MAX_EMAIL_BATCH_CONCURRENCY, 8);
+  const throttle = requestThrottle(client, args, "reverse_email");
+  const creditBudget = createCreditBudget(args.max_credits);
+  const resume = createResumeTracker(args.resume_state, emails, (email) => email.toLowerCase(), resumeTrackerOptions(args));
+  const cache = cacheOptions(args);
+  const cacheStats = { hits: 0, misses: 0, writes: 0 };
+  const errors = [];
+  const results = [];
+  const workEmails = [];
+  for (const email of resume.items) {
+    const validationError = emailValidationError(email);
+    if (validationError) {
+      resume.fail(email);
+      errors.push({ email, code: "invalid_email", error: validationError });
+    } else {
+      workEmails.push(email);
+    }
+  }
+  let requestCount = 0;
+  let creditsUsed = 0;
+  let remainingCredits;
+  const startedAt = Date.now();
+
+  await withConcurrency(workEmails, concurrency, async (email) => {
+    const cachePayload = { email: email.toLowerCase() };
+    const cached = readCachedValue(cache, "reverse_email", cachePayload);
+    if (cached !== undefined) {
+      cacheStats.hits += 1;
+      resume.complete(email);
+      results.push(cached);
+      return;
+    }
+    cacheStats.misses += cache.enabled ? 1 : 0;
+    if (cache.cacheOnly) {
+      resume.fail(email);
+      errors.push({ email, code: "cache_miss", error: "Cache-only mode has no reverse-email cache entry." });
+      return;
+    }
+    const reserved = creditBudget.tryReserve(1);
+    if (!reserved) return;
+    try {
+      await throttle.acquire();
+      const result = await reverseEmail({ email }, client);
+      requestCount += 1;
+      creditsUsed += result.creditsUsed || 0;
+      creditBudget.commit(result.creditsUsed || 0, 1);
+      remainingCredits = minDefined([remainingCredits, result.remainingCredits]);
+      resume.complete(email);
+      const row = result.record ? { email, found: result.found, ...result.record } : { email, found: false };
+      results.push(row);
+      writeCachedValue(cache, "reverse_email", cachePayload, row);
+      if (cache.enabled && cache.canWrite) cacheStats.writes += 1;
+    } catch (error) {
+      creditBudget.release(1);
+      throttle.cooldown(retryAfterMs(error));
+      requestCount += 1;
+      resume.fail(email);
+      errors.push({ email, error: error.message || String(error), data: error.result });
+    }
+  });
+
+  const found = results.filter((row) => row.found !== false && (row.email || row.name || row.employee_linkedin));
+  const result = {
+    ok: errors.length === 0,
+    mode: "reverse_email",
+    inputCount: emails.length,
+    requestCount,
+    foundCount: found.length,
+    creditsUsed,
+    remainingCredits,
+    results,
+    errors: redact(errors),
+    durationMs: Date.now() - startedAt,
+    rateLimitPerMinute: RATE_LIMITS.reverse_email,
+    throttle: throttle.summary(),
+    creditBudget: creditBudget.summary(),
+    cache: cache.enabled ? cacheStats : undefined,
+    export: formatExport(projectRows(found, projectionMode(args), "reverse_email"), exportFormatOption(args.export_format)),
+    resumeState: resume.summary(),
+  };
+  return finalizeRowsResult(result, args, "results", "reverse_email", found);
+}
+
+export async function batchEmployeeSearch(args, client) {
+  args = prepareBulkArgs(args);
+  const persons = uniquePersons([
+    ...(Array.isArray(args.persons) ? args.persons : []),
+    ...recordsFromTextInputs(args),
+  ]);
+  if (!persons.length) throw new Error("persons or input_csv/input_jsonl must include at least one exact-person lookup.");
+  const concurrency = clampInt(args.concurrency, 1, MAX_EMAIL_BATCH_CONCURRENCY, 8);
+  const includePhone = Boolean(args.include_phone);
+  const emailThrottle = requestThrottle(client, args, "employee_search");
+  let phoneThrottle;
+  const creditBudget = createCreditBudget(args.max_credits);
+  const resume = createResumeTracker(args.resume_state, persons, personKey, resumeTrackerOptions(args));
+  const cache = cacheOptions(args);
+  const cacheStats = { hits: 0, misses: 0, writes: 0 };
+  const errors = [];
+  const results = [];
+  let requestCount = 0;
+  let creditsUsed = 0;
+  let remainingCredits;
+  const startedAt = Date.now();
+
+  await withConcurrency(resume.items, concurrency, async (person) => {
+    const cachePayload = { person, include_phone: includePhone };
+    const cached = readCachedValue(cache, "employee_search", cachePayload);
+    if (cached !== undefined) {
+      cacheStats.hits += 1;
+      resume.complete(person);
+      results.push(cached);
+      return;
+    }
+    cacheStats.misses += cache.enabled ? 1 : 0;
+    if (cache.cacheOnly) {
+      resume.fail(person);
+      errors.push({ person, code: "cache_miss", error: "Cache-only mode has no exact-person cache entry." });
+      return;
+    }
+    if (!creditBudget.tryReserve(1)) return;
+    let phoneReserved = false;
+    try {
+      await emailThrottle.acquire();
+      const result = await employeeSearch(person, client);
+      requestCount += 1;
+      creditsUsed += result.creditsUsed || 0;
+      creditBudget.commit(result.creditsUsed || 0, 1);
+      remainingCredits = minDefined([remainingCredits, result.remainingCredits]);
+      let record = result.record ? { ...person, ...result.record, found: result.found } : { ...person, found: false };
+      if (includePhone && result.record) {
+        const canReservePhone = creditBudget.tryReserve(1);
+        if (canReservePhone) {
+          phoneReserved = true;
+          if (!phoneThrottle) {
+            phoneThrottle = requestThrottle(client, { requests_per_minute: args.phone_requests_per_minute, burst_size: args.burst_size }, "phone_search");
+          }
+          try {
+            await phoneThrottle.acquire();
+            const phone = await phoneSearch({
+              linkedin_url: record.employee_linkedin || person.linkedin_url,
+              company_url: record.company_url || person.company_url,
+              first_name: record.first_name || person.first_name,
+              last_name: record.last_name || person.last_name,
+            }, client);
+            requestCount += 1;
+            creditsUsed += phone.creditsUsed || 0;
+            creditBudget.commit(phone.creditsUsed || 0, 1);
+            remainingCredits = minDefined([remainingCredits, phone.remainingCredits]);
+            if (phone.record) record = { ...record, ...cleanObject(phone.record) };
+          } catch (phoneError) {
+            phoneThrottle.cooldown(retryAfterMs(phoneError));
+            creditBudget.release(1);
+            requestCount += 1;
+            errors.push({ person, error: phoneError.message || String(phoneError), data: phoneError.result });
+          }
+        }
+      }
+      resume.complete(person);
+      results.push(record);
+      writeCachedValue(cache, "employee_search", cachePayload, record);
+      if (cache.enabled && cache.canWrite) cacheStats.writes += 1;
+    } catch (error) {
+      emailThrottle.cooldown(retryAfterMs(error));
+      if (phoneThrottle) phoneThrottle.cooldown(retryAfterMs(error));
+      requestCount += 1;
+      creditBudget.release(1);
+      if (phoneReserved) creditBudget.release(1);
+      resume.fail(person);
+      errors.push({ person, error: error.message || String(error), data: error.result });
+    }
+  });
+
+  const found = results.filter((row) => row.found !== false && (row.email || row.phone || row.employee_linkedin));
+  const result = {
+    ok: errors.length === 0,
+    mode: "employee_search",
+    inputCount: persons.length,
+    requestCount,
+    foundCount: found.length,
+    creditsUsed,
+    remainingCredits,
+    results,
+    errors: redact(errors),
+    durationMs: Date.now() - startedAt,
+    rateLimitPerMinute: RATE_LIMITS.employee_search,
+    throttles: {
+      employee_search: emailThrottle.summary(),
+      phone_search: phoneThrottle?.summary(),
+    },
+    creditBudget: creditBudget.summary(),
+    cache: cache.enabled ? cacheStats : undefined,
+    export: formatExport(projectRows(found, projectionMode(args), "employee_search"), exportFormatOption(args.export_format)),
+    resumeState: resume.summary(),
+  };
+  return finalizeRowsResult(result, args, "results", "employee_search", found);
+}
+
+export function planNaturalLanguage(request) {
+  const text = String(request || "").trim();
+  if (!text) throw new Error("request is required.");
+  const lower = text.toLowerCase();
+  const emails = extractEmails(text);
+  const linkedIn = extractLinkedIn(text);
+  const domains = extractDomains(text);
+  const title = titleFromText(lower);
+  const maxCredits = maxCreditsFromText(lower);
+  const inputFormat = inputFormatFromText(lower);
+  const fileBatch = Boolean(inputFormat) || /\b(batch|bulk|list|file|spreadsheet|rows)\b/.test(lower);
+  const exactPersonIntent = /\b(exact|person|people|employee|employees|linkedin)\b/.test(lower)
+    && (fileBatch || /\b(search|enrich|lookup|email|phone|mobile|find)\b/.test(lower));
+
+  if (/auth|status|configured|key/.test(lower)) {
+    return { tool: "quickenrich_auth_status", arguments: {}, confidence: 0.92, rationale: "Request asks about auth/configuration." };
+  }
+  if (/\b(resume|continue|next page|paged|pagination|resume_state)\b/.test(lower) && /\bfinder\b/.test(lower)) {
+    return {
+      tool: "quickenrich_batch_pull_leads",
+      arguments: cleanObject({
+        mode: /compan/.test(lower) ? "company_finder" : /contact|people/.test(lower) ? "contact_finder" : undefined,
+        response: { mode: "meta" },
+      }),
+      requires: ["resume_state", /compan|contact|people/.test(lower) ? undefined : "mode contact_finder or company_finder"].filter(Boolean),
+      confidence: 0.74,
+      rationale: "Request asks to continue finder pagination; batch_pull_leads owns finder resume_state.",
+    };
+  }
+  if (exactPersonIntent || /(?:csv|jsonl).*(person|people|employee|phone)/.test(lower)) {
+    return {
+      tool: fileBatch || /batch|bulk|list/.test(lower) ? "quickenrich_batch_employee_search" : "quickenrich_employee_search",
+      arguments: cleanObject({
+        ...(fileBatch || /batch|bulk|list/.test(lower) ? {} : {
+          linkedin_url: linkedIn,
+          company_url: domains[0],
+          first_name: guessName(text).first,
+          last_name: guessName(text).last,
+        }),
+        include_phone: /phone|mobile|cell/.test(lower) || undefined,
+        max_credits: maxCredits,
+        response: fileBatch ? { mode: "meta" } : undefined,
+      }),
+      requires: fileBatch ? [inputFormat || "persons or input_csv/input_jsonl"] : missingPersonLocatorRequirements({ linkedIn, domains, text }),
+      confidence: linkedIn || fileBatch ? 0.84 : 0.66,
+      rationale: fileBatch ? "Request asks for exact-person batch enrichment from file-shaped input." : "Request appears to ask for exact person enrichment.",
+    };
+  }
+  if ((/reverse|lookup|who/.test(lower) && /email/.test(lower) && fileBatch) || (/email/.test(lower) && inputFormat)) {
+    return {
+      tool: "quickenrich_batch_reverse_email",
+      arguments: cleanObject({
+        emails: emails.length ? emails : undefined,
+        max_credits: maxCredits,
+        response: { mode: "meta" },
+      }),
+      requires: emails.length ? [] : [inputFormat || "emails or input_csv/input_jsonl"],
+      confidence: 0.82,
+      rationale: "Request maps to batch reverse-email lookup from file/list input.",
+    };
+  }
+  if (emails.length > 1 || (emails.length && /batch|bulk|list|csv|jsonl/.test(lower))) {
+    return { tool: "quickenrich_batch_reverse_email", arguments: cleanObject({ emails, max_credits: maxCredits }), confidence: 0.9, rationale: "Request contains multiple or batch email lookups; using deduped batch reverse-email." };
+  }
+  if (emails.length && /reverse|lookup|who|person|phone|enrich/.test(lower)) {
+    return { tool: "quickenrich_reverse_email", arguments: { email: emails[0] }, confidence: 0.84, rationale: "Request contains an email address and asks for lookup/enrichment." };
+  }
+  if (/contact finder|contacts|people database/.test(lower)) {
+    return {
+      tool: "quickenrich_batch_pull_leads",
+      arguments: { mode: "contact_finder", body: cleanObject({ company_url: domains[0], title: title || undefined, page: 1, per_page: 20 }), max_results: 20, pages_per_company: 1 },
+      confidence: 0.78,
+      rationale: "Request asks for contact discovery; using batch_pull_leads contact_finder for pagination and compact envelopes.",
+    };
+  }
+  if (/\b(pipeline|workflow|chain|then)\b/.test(lower) && /compan/.test(lower) && /\b(domain|lead|contact|people)\b/.test(lower)) {
+    return {
+      tool: "quickenrich_pipeline",
+      arguments: cleanObject({
+        mode: "company_finder_to_domain_search",
+        title: title || (/founder|founders/.test(lower) ? FOUNDER_TITLE : undefined),
+        max_credits: maxCredits,
+        projection: /email/.test(lower) ? "emails" : /compan/.test(lower) && !/people|contact|lead/.test(lower) ? "companies" : "people",
+        response: { mode: "meta" },
+      }),
+      requires: ["filters/body or company-finder criteria"],
+      confidence: 0.8,
+      rationale: "Request asks for a chained company-discovery to lead-pull workflow.",
+    };
+  }
+  if (/company finder|companies|firmographic/.test(lower)) {
+    return {
+      tool: "quickenrich_batch_pull_leads",
+      arguments: cleanObject({ mode: "company_finder", body: cleanObject({ company_url: domains[0], page: 1, per_page: 20 }), max_results: 20, pages_per_company: 1, max_credits: maxCredits }),
+      confidence: 0.78,
+      rationale: "Request asks for company discovery; using batch_pull_leads company_finder for pagination, credit guard, and compact envelopes.",
+    };
+  }
+  if (linkedIn || (/email|enrich|find/.test(lower) && domains.length)) {
+    return {
+      tool: "quickenrich_employee_search",
+      arguments: cleanObject({
+        linkedin_url: linkedIn,
+        company_url: domains[0],
+        first_name: guessName(text).first,
+        last_name: guessName(text).last,
+      }),
+      confidence: linkedIn ? 0.88 : 0.62,
+      rationale: "Request appears to ask for exact person enrichment.",
+    };
+  }
+  if (/batch|pull|lead|leads|founder|founders|ceo|owner|domain[_\s-]?search|company domains?|domains?/.test(lower) || domains.length > 1) {
+    return {
+      tool: "quickenrich_batch_pull_leads",
+      arguments: cleanObject({
+        mode: "domain_search",
+        companies: !inputFormat && domains.length ? domains.map((domain) => ({ company_url: domain, title: title || undefined })) : undefined,
+        title: title || (/founder|founders/.test(lower) ? FOUNDER_TITLE : undefined),
+        per_company_limit: 20,
+        pages_per_company: 1,
+        concurrency: 8,
+        has_email: /email|emails|reachable|verified/.test(lower) ? true : undefined,
+        max_credits: maxCredits,
+        response: domains.length && !inputFormat ? undefined : { mode: "meta" },
+      }),
+      requires: inputFormat ? [inputFormat] : domains.length ? [] : ["companies or input_csv/input_jsonl"],
+      confidence: domains.length ? 0.86 : 0.54,
+      rationale: "Request maps to a domain-based batch lead pull.",
+    };
+  }
+  return {
+    tool: "quickenrich_agent_graph",
+    arguments: {},
+    confidence: 0.35,
+    rationale: "Could not confidently map the request; returning the capability graph.",
+  };
+}
+
+export async function naturalLanguage(args, client) {
+  const plan = planNaturalLanguage(args.request);
+  if (!args.execute) {
+    return { ok: true, execute: false, plan };
+  }
+  if (plan.requires?.length) {
+    return { ok: false, execute: false, plan, error: `Plan requires: ${plan.requires.join(", ")}` };
+  }
+  const result = await callQuickEnrichTool(plan.tool, { ...plan.arguments, response: args.response }, client);
+  return { ok: true, execute: true, plan, result };
+}
+
+function inputFormatFromText(lower) {
+  if (/\bjsonl\b|json lines|ndjson/.test(lower)) return "input_jsonl";
+  if (/\bcsv\b|spreadsheet/.test(lower)) return "input_csv";
+  return "";
+}
+
+function maxCreditsFromText(lower) {
+  const patterns = [
+    /\bmax(?:imum)?\D{0,12}(\d{1,8})\s+credits?\b/i,
+    /\bmax(?:imum)?(?:_|\s|-)*credits?\D{0,12}(\d{1,8})\b/i,
+    /\bcredit(?:s)?(?:_|\s|-)*max\D{0,12}(\d{1,8})\b/i,
+    /\bcap(?:ped)?(?: at)?\D{0,12}(\d{1,8})\s+credits?\b/i,
+    /\b(\d{1,8})\s+credits?\s+(?:max|budget|cap)\b/i,
+  ];
+  for (const pattern of patterns) {
+    const match = lower.match(pattern);
+    const value = Number(match?.[1]);
+    if (Number.isFinite(value) && value >= 0) return Math.floor(value);
+  }
+  return undefined;
+}
+
+function missingPersonLocatorRequirements({ linkedIn, domains, text }) {
+  if (linkedIn) return [];
+  const guessed = guessName(text);
+  if (domains.length && guessed.first && guessed.last) return [];
+  const missing = [];
+  if (!domains.length) missing.push("linkedin_url or company_url");
+  if (!guessed.first || !guessed.last) missing.push("first_name and last_name");
+  return missing;
+}
+
+function normalizedSingle(endpoint, response, includeRaw = false) {
+  const record = firstRecord(response.data);
+  return {
+    ok: true,
+    endpoint,
+    found: Boolean(record && Object.keys(record).length),
+    record: record ? normalizeLead(record, endpoint) : null,
+    meta: response.data?.meta,
+    creditsUsed: numericMeta(response.data?.meta?.credits_used, 0),
+    remainingCredits: numericMeta(response.data?.meta?.remaining_credits),
+    rateLimit: response.rateLimit,
+    rateLimitPerMinute: RATE_LIMITS[endpoint],
+    raw: includeRaw ? response.data : undefined,
+  };
+}
+
+function normalizedList(endpoint, response, includeRaw = false) {
+  const rows = records(response.data);
+  const normalized = endpoint === "company_finder"
+    ? rows.map((row) => normalizeCompany(row))
+    : rows.map((row) => normalizeLead(row, endpoint));
+  return {
+    ok: true,
+    endpoint,
+    count: rows.length,
+    records: normalized,
+    meta: response.data?.meta,
+    creditsUsed: numericMeta(response.data?.meta?.credits_used, 0),
+    remainingCredits: numericMeta(response.data?.meta?.remaining_credits),
+    rateLimit: response.rateLimit,
+    rateLimitPerMinute: RATE_LIMITS[endpoint],
+    raw: includeRaw ? response.data : undefined,
+  };
+}
+
+async function pullCompanyDomainLeads(company, options, client) {
+  const leads = [];
+  const errors = [];
+  const pageCreditEstimate = Math.max(1, Number(options.creditEstimate || 1));
+  let requestCount = 0;
+  let creditsUsed = 0;
+  let remainingCredits;
+  for (let page = 1; page <= options.pagesPerCompany; page += 1) {
+    if (leads.length >= options.perCompanyLimit) break;
+    if (options.creditBudget && !options.creditBudget.tryReserve(pageCreditEstimate)) break;
+    try {
+      await options.throttle?.acquire();
+      const result = await domainSearch({
+        company_url: company.company_url,
+        title: options.title,
+        has_email: options.hasEmail,
+        page,
+        per_page: options.perPage,
+        include_raw: false,
+      }, client);
+      requestCount += 1;
+      creditsUsed += result.creditsUsed || 0;
+      options.creditBudget?.commit(result.creditsUsed || 0, pageCreditEstimate);
+      remainingCredits = minDefined([remainingCredits, result.remainingCredits]);
+      leads.push(...(result.records || []).map((lead) => ({ ...lead, batch_company_url: company.company_url })));
+      const lastPage = Number(result.meta?.last_page || 0);
+      if (lastPage && page >= lastPage) break;
+    } catch (error) {
+      options.throttle?.cooldown(retryAfterMs(error));
+      requestCount += 1;
+      options.creditBudget?.release(pageCreditEstimate);
+      errors.push({ company_url: company.company_url, error: error.message || String(error), data: error.result });
+      break;
+    }
+  }
+  return { company, leads: leads.slice(0, options.perCompanyLimit), errors: redact(errors), requestCount, creditsUsed, remainingCredits };
+}
+
+async function enrichLeads(leads, options, client) {
+  const targets = leads
+    .filter((lead) => !lead.email && (lead.has_email || lead.employee_linkedin) && canLocatePerson(lead))
+    .slice(0, options.maxEnrichments);
+  const errors = [];
+  let enrichmentRequests = 0;
+  let creditsUsed = 0;
+  let remainingCredits;
+  const enrichedByKey = new Map();
+  const emailThrottle = requestThrottle(client, {}, "employee_search");
+  let phoneThrottle;
+  await withConcurrency(targets, options.concurrency, async (lead) => {
+    if (options.creditBudget && !options.creditBudget.tryReserve(1)) return;
+    try {
+      await emailThrottle.acquire();
+      const result = await employeeSearch({
+        linkedin_url: lead.employee_linkedin,
+        company_url: lead.company_url,
+        first_name: lead.first_name,
+        last_name: lead.last_name,
+      }, client);
+      enrichmentRequests += 1;
+      creditsUsed += result.creditsUsed || 0;
+      options.creditBudget?.commit(result.creditsUsed || 0, 1);
+      remainingCredits = minDefined([remainingCredits, result.remainingCredits]);
+      let merged = result.record ? { ...lead, ...cleanObject(result.record) } : lead;
+      if (options.includePhone && !merged.phone) {
+        const phoneReserved = options.creditBudget ? options.creditBudget.tryReserve(1) : true;
+        if (phoneReserved) {
+          if (!phoneThrottle) {
+            phoneThrottle = requestThrottle(client, {}, "phone_search");
+          }
+          try {
+            await phoneThrottle.acquire();
+            const phone = await phoneSearch({
+              linkedin_url: merged.employee_linkedin,
+              company_url: merged.company_url,
+              first_name: merged.first_name,
+              last_name: merged.last_name,
+            }, client);
+            enrichmentRequests += 1;
+            creditsUsed += phone.creditsUsed || 0;
+            options.creditBudget?.commit(phone.creditsUsed || 0, 1);
+            remainingCredits = minDefined([remainingCredits, phone.remainingCredits]);
+            if (phone.record) merged = { ...merged, ...cleanObject(phone.record) };
+          } catch (error) {
+            options.creditBudget?.release(1);
+            errors.push({ lead: compactValue(lead, responseOptions({ mode: "compact", maxItems: 1 })), error: error.message || String(error), data: error.result });
+          }
+        }
+      }
+      enrichedByKey.set(leadKey(lead), merged);
+    } catch (error) {
+      emailThrottle.cooldown(retryAfterMs(error));
+      if (phoneThrottle) phoneThrottle.cooldown(retryAfterMs(error));
+      enrichmentRequests += 1;
+      options.creditBudget?.release(1);
+      errors.push({ lead: compactValue(lead, responseOptions({ mode: "compact", maxItems: 1 })), error: error.message || String(error), data: error.result });
+    }
+  });
+  return {
+    leads: leads.map((lead) => enrichedByKey.get(leadKey(lead)) || lead),
+    enrichmentRequests,
+    creditsUsed,
+    remainingCredits,
+    errors: redact(errors),
+  };
+}
+
+function batchPlan(details) {
+  return {
+    ok: true,
+    dryRun: true,
+    mode: details.mode,
+    plannedRequests: details.plannedRequests,
+    inputCompanyCount: details.inputCompanyCount,
+    companies: details.companies,
+    concurrency: details.concurrency,
+    perPage: details.perPage,
+    pagesPerCompany: details.pagesPerCompany,
+    perCompanyLimit: details.perCompanyLimit,
+    rateLimitPerMinute: RATE_LIMITS[details.mode],
+    throttle: details.throttle,
+    creditBudget: details.creditBudget,
+    resumeState: details.resumeState,
+    creditNotes: agentGraph().creditNotes[details.mode],
+  };
+}
+
+function throttleOptions(args = {}, endpoint = "domain_search") {
+  const publishedLimit = RATE_LIMITS[endpoint] || 1000;
+  const envPrefix = `QUICKENRICH_${endpoint.toUpperCase()}`;
+  const requestedScope = String(args.throttle_scope || process.env.QUICKENRICH_MCP_THROTTLE_SCOPE || "process").toLowerCase();
+  const defaultRpm = endpoint === "domain_search"
+    ? DEFAULT_DOMAIN_SEARCH_RPM
+    : positiveInteger(process.env[`${envPrefix}_REQUESTS_PER_MINUTE`], publishedLimit);
+  const defaultBurst = endpoint === "domain_search"
+    ? DEFAULT_DOMAIN_SEARCH_BURST
+    : positiveInteger(process.env[`${envPrefix}_BURST_SIZE`], DEFAULT_BURSTS[endpoint] || 4);
+  const requestsPerMinute = clampInt(
+    args.requests_per_minute ?? defaultRpm,
+    1,
+    100_000,
+    publishedLimit,
+  );
+  const burstSize = clampInt(
+    args.burst_size ?? defaultBurst,
+    1,
+    10_000,
+    1,
+  );
+  return {
+    requestsPerMinute,
+    burstSize,
+    publishedLimit,
+    endpoint,
+    scope: requestedScope === "shared" ? "shared" : "process",
+    abovePublishedLimit: requestsPerMinute > publishedLimit || undefined,
+    requiresProviderApproval: requestsPerMinute > publishedLimit || undefined,
+  };
+}
+
+function requestThrottle(client, args = {}, endpoint = "domain_search") {
+  const options = throttleOptions(args, endpoint);
+  const limiter = options.scope === "shared"
+    ? createSharedTokenBucketLimiter(options)
+    : typeof client?.throttleLimiter === "function"
+    ? client.throttleLimiter(options)
+    : createTokenBucketLimiter(options);
+  return createRequestThrottle(options, limiter);
+}
+
+function createRequestThrottle(options, limiter = createTokenBucketLimiter(options)) {
+  const requestsPerMinute = options.requestsPerMinute;
+  const burstSize = options.burstSize;
+  const intervalMs = 60_000 / requestsPerMinute;
+  let acquired = 0;
+  let sleptMs = 0;
+
+  async function acquire() {
+    acquired += 1;
+    sleptMs += await limiter.acquire();
+  }
+
+  function cooldown(ms) {
+    limiter.cooldown(ms);
+  }
+
+  function summary() {
+    return {
+      requestsPerMinute,
+      publishedLimit: options.publishedLimit,
+      abovePublishedLimit: requestsPerMinute > options.publishedLimit || undefined,
+      requiresProviderApproval: requestsPerMinute > options.publishedLimit || undefined,
+      scope: options.scope || "process",
+      burstSize,
+      intervalMs: Math.round(intervalMs * 100) / 100,
+      acquired,
+      sleptMs: Math.round(sleptMs),
+    };
+  }
+
+  return { acquire, cooldown, summary };
+}
+
+function createSharedTokenBucketLimiter(options) {
+  const local = createTokenBucketLimiter(options);
+  let cooldownUntil = 0;
+  return {
+    async acquire() {
+      const localSlept = await local.acquire();
+      const cooldownWait = Math.max(0, cooldownUntil - Date.now());
+      if (cooldownWait > 0) await sleep(cooldownWait);
+      return localSlept + cooldownWait + await acquireSharedPermit(options);
+    },
+    cooldown(ms) {
+      local.cooldown(ms);
+      const waitMs = Number(ms);
+      if (Number.isFinite(waitMs) && waitMs > 0) cooldownUntil = Math.max(cooldownUntil, Date.now() + waitMs);
+    },
+  };
+}
+
+async function acquireSharedPermit(options) {
+  const dir = process.env.QUICKENRICH_MCP_SHARED_THROTTLE_DIR || join(DEFAULT_DATA_DIR, "throttle");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const safeEndpoint = String(options.endpoint || "request").replace(/[^a-z0-9_-]/gi, "_");
+  const statePath = join(dir, `${safeEndpoint}-${options.requestsPerMinute}.json`);
+  const lockPath = `${statePath}.lock`;
+  const windowMs = 60_000;
+  let slept = 0;
+
+  while (true) {
+    await acquireFileLock(lockPath);
+    let waitMs = 0;
+    try {
+      const now = Date.now();
+      const state = readJsonFile(statePath) || {};
+      const starts = Array.isArray(state.starts) ? state.starts.filter((value) => Number(value) > now - windowMs).map(Number) : [];
+      if (starts.length < options.requestsPerMinute) {
+        starts.push(now);
+        writeJsonFileAtomic(statePath, { starts });
+        return slept;
+      }
+      waitMs = Math.max(1, Math.min(60_000, starts[0] + windowMs - now));
+      writeJsonFileAtomic(statePath, { starts });
+    } finally {
+      rmSync(lockPath, { recursive: true, force: true });
+    }
+    slept += waitMs;
+    await sleep(waitMs);
+  }
+}
+
+async function acquireFileLock(lockPath) {
+  while (true) {
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+      return;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      await sleep(5);
+    }
+  }
+}
+
+function createTokenBucketLimiter(options) {
+  const requestsPerMinute = options.requestsPerMinute;
+  const burstSize = options.burstSize;
+  const intervalMs = 60_000 / requestsPerMinute;
+  const windowMs = 60_000;
+  let chain = Promise.resolve();
+  let tokens = burstSize;
+  let updatedAt = Date.now();
+  let cooldownUntil = 0;
+  let windowStarts = [];
+  let windowOffset = 0;
+
+  function refill(now) {
+    const elapsed = Math.max(0, now - updatedAt);
+    if (elapsed > 0) {
+      tokens = Math.min(burstSize, tokens + elapsed / intervalMs);
+      updatedAt = now;
+    }
+  }
+
+  function pruneWindow(now) {
+    const cutoff = now - windowMs;
+    while (windowOffset < windowStarts.length && windowStarts[windowOffset] <= cutoff) {
+      windowOffset += 1;
+    }
+    if (windowOffset > 1024 && windowOffset * 2 > windowStarts.length) {
+      windowStarts = windowStarts.slice(windowOffset);
+      windowOffset = 0;
+    }
+  }
+
+  function rollingWindowWait(now) {
+    pruneWindow(now);
+    if (windowStarts.length - windowOffset < requestsPerMinute) return 0;
+    return Math.max(1, windowStarts[windowOffset] + windowMs - now);
+  }
+
+  async function acquire() {
+    let totalSlept = 0;
+    while (true) {
+      let waitMs = 0;
+      let permitGranted = false;
+      let release;
+      const previous = chain;
+      chain = new Promise((resolve) => {
+        release = resolve;
+      });
+
+      await previous;
+      try {
+        const now = Date.now();
+        refill(now);
+        const cooldownWait = Math.max(0, cooldownUntil - now);
+        if (cooldownWait > 0) {
+          waitMs = cooldownWait;
+        } else {
+          const windowWait = rollingWindowWait(now);
+          if (windowWait > 0) {
+            waitMs = windowWait;
+          } else if (tokens >= 1) {
+            tokens -= 1;
+            windowStarts.push(now);
+            permitGranted = true;
+          } else {
+            waitMs = Math.max(1, (1 - tokens) * intervalMs);
+          }
+        }
+      } finally {
+        release();
+      }
+
+      if (permitGranted) {
+        return totalSlept;
+      }
+
+      totalSlept += waitMs;
+      await sleep(waitMs);
+    }
+  }
+
+  function cooldown(ms) {
+    const waitMs = Number(ms);
+    if (!Number.isFinite(waitMs) || waitMs <= 0) return;
+    cooldownUntil = Math.max(cooldownUntil, Date.now() + waitMs);
+  }
+
+  return { acquire, cooldown };
+}
+
+function uniqueDomainSearchCompanies(companies, defaultTitle) {
+  const seen = new Map();
+  for (const company of companies) {
+    const title = company.title || defaultTitle || "";
+    const key = `${normalizeDomainKey(company.company_url)}\n${title.toLowerCase().trim()}`;
+    if (!seen.has(key)) seen.set(key, { ...company, title });
+  }
+  return [...seen.values()];
+}
+
+function normalizeDomainKey(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/^www\./, "")
+    .replace(/\/.*$/, "");
+}
+
+function domainSearchBatchKey(company) {
+  return `${normalizeDomainKey(company.company_url)}|${String(company.title || "").trim().toLowerCase()}`;
+}
+
+function normalizeCompanyInputs(input) {
+  const rows = Array.isArray(input) ? input : [];
+  const companies = rows.map((row) => {
+    if (typeof row === "string") return { company_url: row };
+    return {
+      company_url: row.company_url || row.domain || row.url,
+      company_name: row.company_name || row.name,
+      title: row.title,
+    };
+  }).filter((row) => row.company_url);
+  if (!companies.length) throw new Error("companies must include at least one company_url or domain.");
+  return companies;
+}
+
+async function pagedFinder(mode, args, options, client) {
+  const throttle = requestThrottle(client, args, mode);
+  const recordsOut = [];
+  const errors = [];
+  let requestCount = 0;
+  let creditsUsed = 0;
+  let remainingCredits;
+  const fingerprint = finderRequestFingerprint(mode, args);
+  const startPage = finderResumeStartPage(args.resume_state, mode, fingerprint, clampInt(args.page, 1, 10_000, 1));
+  const pages = Array.from({ length: options.maxPages }, (_, index) => ({ page: startPage + index }));
+  const resume = createResumeTracker(args.resume_state, pages, (entry) => finderPageKey(mode, fingerprint, entry.page), resumeTrackerOptions(args));
+  let terminalPage;
+
+  const creditEstimate = Number(options.creditEstimate || 0);
+  const creditLimited = options.creditBudget?.limited && creditEstimate > 0;
+
+  async function fetchPage(entry) {
+    const page = entry.page;
+    const hasCreditCharge = creditLimited;
+    const pageCreditEstimate = creditLimited && mode === "company_finder"
+      ? Math.max(1, Math.min(options.perPage, options.creditBudget.remaining()))
+      : creditEstimate;
+    const hasReserved = hasCreditCharge ? options.creditBudget.tryReserve(pageCreditEstimate) : true;
+    if (!hasReserved) {
+      return { ok: false, entry, page, skipped: true, error: new Error("Credit budget exhausted.") };
+    }
+    try {
+      await throttle.acquire();
+      const perPage = creditLimited && mode === "company_finder"
+        ? pageCreditEstimate
+        : options.perPage;
+      const callArgs = { ...args, page, per_page: perPage, include_raw: false, validate_filters: false };
+      const result = mode === "company_finder"
+        ? await companyFinder(callArgs, client)
+        : await contactFinder(callArgs, client);
+      if (options.creditBudget && creditEstimate > 0) {
+        options.creditBudget.commit(result.creditsUsed || 0, pageCreditEstimate);
+      }
+      return { ok: true, entry, page, result };
+    } catch (error) {
+      throttle.cooldown(retryAfterMs(error));
+      if (options.creditBudget && creditEstimate > 0) {
+        options.creditBudget.release(pageCreditEstimate);
+      }
+      return { ok: false, entry, page, error };
+    }
+  }
+
+  function applyPageOutcome(outcome) {
+    if (!outcome.ok) {
+      if (outcome.skipped) return;
+      requestCount += 1;
+      resume.fail(outcome.entry);
+      errors.push({ page: outcome.page, error: outcome.error.message || String(outcome.error), data: outcome.error.result });
+      return;
+    }
+    requestCount += 1;
+    const result = outcome.result;
+    creditsUsed += result.creditsUsed || 0;
+    remainingCredits = minDefined([remainingCredits, result.remainingCredits]);
+    recordsOut.push(...(result.records || []));
+    resume.complete(outcome.entry);
+    const lastPage = Number(result.meta?.last_page || 0);
+    if (lastPage && outcome.page >= lastPage) {
+      terminalPage = lastPage;
+      for (const future of pages) {
+        if (future.page > lastPage) resume.skip(future);
+      }
+    }
+  }
+
+  async function runSequential(items) {
+    for (const entry of items) {
+      if (recordsOut.length >= options.maxResults) break;
+      const outcome = await fetchPage(entry);
+      applyPageOutcome(outcome);
+      if (!outcome.ok || (terminalPage && entry.page >= terminalPage)) break;
+    }
+  }
+
+  const concurrency = clampInt(options.concurrency, 1, MAX_BATCH_CONCURRENCY, 1);
+  const shouldRunSequentially = concurrency <= 1 || resume.items.length <= 1;
+  if (shouldRunSequentially) {
+    await runSequential(resume.items);
+  } else {
+    const [first, ...rest] = resume.items;
+    if (first && recordsOut.length < options.maxResults) {
+      const firstOutcome = await fetchPage(first);
+      applyPageOutcome(firstOutcome);
+      if (firstOutcome.ok && recordsOut.length < options.maxResults && (!terminalPage || first.page < terminalPage)) {
+        const remainingPageBudget = Math.max(0, Math.ceil((options.maxResults - recordsOut.length) / options.perPage));
+        const creditBudgetPages = creditLimited
+          ? mode === "company_finder"
+            ? Math.floor(options.creditBudget?.remaining() || 0)
+            : Math.floor((options.creditBudget?.remaining() || 0) / creditEstimate)
+          : remainingPageBudget;
+        const maxFanout = Math.max(0, creditLimited ? Math.min(remainingPageBudget, creditBudgetPages) : remainingPageBudget);
+        const fanoutItems = rest
+          .filter((entry) => !terminalPage || entry.page <= terminalPage)
+          .slice(0, maxFanout);
+        const outcomes = await withConcurrency(fanoutItems, concurrency, fetchPage);
+        for (const outcome of outcomes.sort((a, b) => a.page - b.page)) {
+          applyPageOutcome(outcome);
+        }
+      }
+    }
+  }
+  const resumeState = finderResumeSummary(resume, pages, mode, fingerprint, terminalPage);
+  return {
+    records: recordsOut.slice(0, options.maxResults),
+    requestCount,
+    creditsUsed,
+    remainingCredits,
+    errors: redact(errors),
+    throttle: throttle.summary(),
+    resumeState,
+  };
+}
+
+function contactFinderBody(args) {
+  return cleanObject({
+    ...(args.body && typeof args.body === "object" ? args.body : {}),
+    ...typedFinderFilters(args, CONTACT_FILTER_FIELDS),
+    ...cleanObject({
+      has_email: boolOrUndefined(args.has_email),
+      has_phone: boolOrUndefined(args.has_phone),
+    }),
+    page: args.page,
+    per_page: args.per_page,
+  });
+}
+
+function companyFinderBody(args) {
+  return cleanObject({
+    ...(args.body && typeof args.body === "object" ? args.body : {}),
+    ...typedFinderFilters(args, COMPANY_FILTER_FIELDS),
+    ...cleanObject({ company_url: args.company_url }),
+    page: args.page,
+    per_page: args.per_page,
+  });
+}
+
+function finderRequestFingerprint(mode, args) {
+  const body = mode === "company_finder" ? companyFinderBody(args) : contactFinderBody(args);
+  const normalized = { ...body };
+  delete normalized.page;
+  delete normalized.per_page;
+  return createHash("sha1")
+    .update(stableStringify({ mode, body: normalized }))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+function finderPageKey(mode, fingerprint, page) {
+  return `${mode}:${fingerprint}:page:${page}`;
+}
+
+function finderResumeStartPage(state, mode, fingerprint, fallback) {
+  if (state?.fingerprint && state.fingerprint !== fingerprint) return fallback;
+  const nextPage = Number(state?.nextPage);
+  if (Number.isFinite(nextPage) && nextPage > 0) return Math.floor(nextPage);
+  const pendingPages = arrayOfStrings(state?.pending)
+    .map((key) => key.match(new RegExp(`^${mode}:${fingerprint}:page:(\\d+)$`))?.[1])
+    .filter(Boolean)
+    .map(Number)
+    .filter(Number.isFinite);
+  return pendingPages.length ? Math.min(...pendingPages) : fallback;
+}
+
+function finderResumeSummary(resume, pages, mode, fingerprint, terminalPage) {
+  const summary = resume.summary();
+  const pendingPages = pages
+    .filter((entry) => summary.pending.includes(finderPageKey(mode, fingerprint, entry.page)))
+    .map((entry) => entry.page);
+  return cleanObject({
+    ...summary,
+    fingerprint,
+    nextPage: pendingPages.length ? Math.min(...pendingPages) : undefined,
+    terminalPage,
+  });
+}
+
+const CONTACT_FILTER_FIELDS = [
+  "company_name",
+  "city",
+  "country_code",
+  "industry_linkedin",
+  "number_of_employees",
+  "revenue",
+  "title",
+  "locality",
+];
+
+const COMPANY_FILTER_FIELDS = [
+  "home_page_text",
+  "bio_li",
+  "services",
+  "industry",
+  "number_of_employees",
+  "revenue",
+  "country_code",
+  "city",
+  "company_name",
+];
+
+function typedFinderFilters(args, fields) {
+  const source = args.filters && typeof args.filters === "object" ? args.filters : args;
+  const output = {};
+  for (const field of fields) {
+    const filter = normalizeFinderFilter(source[field]);
+    if (filter) output[field] = filter;
+  }
+  return output;
+}
+
+function normalizeFinderFilter(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (Array.isArray(value) || typeof value === "string" || typeof value === "number") {
+    const include = arrayOfStrings(value);
+    return include.length ? { include, exclude: [] } : undefined;
+  }
+  if (typeof value === "object") {
+    const include = arrayOfStrings(value.include);
+    const exclude = arrayOfStrings(value.exclude);
+    if (!include.length && !exclude.length) return undefined;
+    return { include, exclude };
+  }
+  return undefined;
+}
+
+async function validateFinderFilters(mode, args, client) {
+  const body = mode === "company_finder" ? companyFinderBody(args) : contactFinderBody(args);
+  const spec = mode === "company_finder" ? COMPANY_VALIDATED_FIELDS : CONTACT_VALIDATED_FIELDS;
+  const errors = [];
+  const checked = [];
+  for (const [field, lookup] of Object.entries(spec)) {
+    const values = finderFieldValues(body[field]);
+    if (!values.length) continue;
+    checked.push({ field, lookup, values });
+    const allowed = await lookupAllowedValues(lookup, client);
+    for (const value of values) {
+      if (!allowed.has(value.toLowerCase())) {
+        errors.push({ field, value, lookup, message: `${field} must match ${lookup} lookup values.` });
+      }
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    mode,
+    checked,
+    errors,
+  };
+}
+
+const CONTACT_VALIDATED_FIELDS = {
+  country_code: "country_codes",
+  industry_linkedin: "industries",
+  number_of_employees: "employee_ranges",
+  revenue: "revenue_ranges",
+};
+
+const COMPANY_VALIDATED_FIELDS = {
+  services: "company_services",
+  industry: "industries",
+  country_code: "country_codes",
+  number_of_employees: "employee_ranges",
+  revenue: "revenue_ranges",
+};
+
+const lookupCache = new Map();
+
+async function lookupAllowedValues(lookup, client) {
+  const key = `${lookup}:all`;
+  if (lookupCache.has(key)) return lookupCache.get(key);
+  const result = await lookupValues({ lookup }, client);
+  const values = new Set(extractLookupValues(result.data, lookup).map((value) => value.toLowerCase()));
+  lookupCache.set(key, values);
+  return values;
+}
+
+function extractLookupValues(data, lookup) {
+  if (Array.isArray(data)) {
+    return data.flatMap((entry) => {
+      if (typeof entry === "string") return [entry];
+      if (!entry || typeof entry !== "object") return [];
+      return [
+        entry.service,
+        entry.name,
+        entry.value,
+        entry.label,
+        entry.industry,
+        entry.country_code,
+        entry.country_code_2_character,
+        entry.range,
+      ].filter(Boolean);
+    }).map(String);
+  }
+  if (data && typeof data === "object") {
+    return extractLookupValues(data.data || data.values || data.results || [], lookup);
+  }
+  return [];
+}
+
+function finderFieldValues(value) {
+  if (!value) return [];
+  if (typeof value === "object" && !Array.isArray(value)) {
+    return [...arrayOfStrings(value.include), ...arrayOfStrings(value.exclude)];
+  }
+  return arrayOfStrings(value);
+}
+
+function normalizeLead(row, source) {
+  const first = cleanString(row.first_name || row.firstName);
+  const last = cleanString(row.last_name || row.lastName);
+  const name = cleanString(row.name || [first, last].filter(Boolean).join(" "));
+  return cleanObject({
+    source,
+    first_name: first,
+    last_name: last,
+    name,
+    title: cleanString(row.title || row.job_title || row.jobTitle),
+    email: cleanString(row.email || row.employee_email),
+    phone: normalizePhone(row.employee_phone || row.phone || row.mobile_phone),
+    employee_linkedin: cleanString(row.employee_linkedin || row.linkedin_url || row.linkedin || row.linkedinLink),
+    has_email: boolOrUndefined(row.has_email),
+    has_phone: boolOrUndefined(row.has_phone),
+    company_url: cleanString(row.company_url || row.website || row.domain),
+    company_name: cleanString(row.company_name || row.company || row.name_company),
+    email_domain: cleanString(row.email_domain),
+    company_phone: normalizePhone(row.company_phone),
+    employee_count: cleanString(row.employee_count || row.number_of_employees),
+    revenue: cleanString(row.revenue),
+    industry: cleanString(row.industry || row.industry_linkedin),
+    city: cleanString(row.city),
+    locality: cleanString(row.locality),
+    region_code: cleanString(row.region_code),
+    country_code: cleanString(row.country_code),
+  });
+}
+
+function normalizeCompany(row) {
+  const domain = cleanString(row.url || row.company_url || row.domain || row.email_domain || row.final_email_domain);
+  return cleanObject({
+    source: "company_finder",
+    company_name: cleanString(row.company_name || row.name || row.company),
+    domain,
+    url: cleanString(row.url || row.website || domain),
+    email_domain: cleanString(row.email_domain),
+    final_email_domain: cleanString(row.final_email_domain),
+    phone: normalizePhone(row.phone || row.company_phone),
+    linkedin_url: cleanString(row.linkedin_url || row.company_linkedin || row.company_linked),
+    city: cleanString(row.city),
+    region_code: cleanString(row.region_code),
+    country_code: cleanString(row.country_code),
+    industry: cleanString(row.industry || row.industry_linkedin),
+    employee_count: cleanString(row.employee_count || row.number_of_employees),
+    revenue: cleanString(row.revenue),
+    services: Array.isArray(row.services) ? row.services.map(cleanString).filter(Boolean) : undefined,
+    service_count: numericMeta(row.service_count),
+    home_page_text_snippet: cleanString(row.home_page_text_snippet),
+    bio_li_snippet: cleanString(row.bio_li_snippet),
+  });
+}
+
+function records(payload) {
+  const data = payload?.data;
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object") return [data];
+  if (Array.isArray(payload)) return payload;
+  return [];
+}
+
+function firstRecord(payload) {
+  return records(payload)[0] || null;
+}
+
+function requirePersonLocator(args) {
+  if (args.linkedin_url) return;
+  if (args.company_url && args.first_name && args.last_name) return;
+  throw new Error("Provide linkedin_url or company_url + first_name + last_name.");
+}
+
+function canLocatePerson(lead) {
+  return Boolean(lead.employee_linkedin || (lead.company_url && lead.first_name && lead.last_name));
+}
+
+function titleFromText(lower) {
+  if (/founder|cofounder|co-founder/.test(lower)) return FOUNDER_TITLE;
+  if (/\bceo\b|chief executive/.test(lower)) return "CEO";
+  if (/\bowner\b/.test(lower)) return "Owner";
+  if (/\bpresident\b/.test(lower)) return "President";
+  return "";
+}
+
+function guessName(text) {
+  const match = text.match(/\b([A-Z][a-z]+)\s+([A-Z][a-z]+)\b/);
+  return { first: match?.[1], last: match?.[2] };
+}
+
+function extractEmails(text) {
+  return [...text.matchAll(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi)].map((m) => m[0]);
+}
+
+function extractLinkedIn(text) {
+  const match = text.match(/https?:\/\/(?:www\.)?linkedin\.com\/in\/[^\s,;)"']+/i);
+  return match?.[0];
+}
+
+function extractDomains(text) {
+  const out = [];
+  const seen = new Set();
+  const matches = text.matchAll(/\b(?:https?:\/\/)?(?:www\.)?([a-z0-9][a-z0-9-]*(?:\.[a-z0-9-]+)+)(?:\/[^\s,;)"']*)?/gi);
+  for (const match of matches) {
+    const raw = match[0].replace(/[.,;:)]+$/, "");
+    if (/linkedin\.com|quickenrich\.io/i.test(raw)) continue;
+    const value = raw.startsWith("http") ? raw : match[1];
+    const key = value.toLowerCase();
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(value);
+    }
+  }
+  return out;
+}
+
+function dedupeLeads(leads) {
+  const map = new Map();
+  for (const lead of leads) {
+    const key = leadKey(lead);
+    if (!map.has(key)) map.set(key, lead);
+    else map.set(key, { ...map.get(key), ...cleanObject(lead) });
+  }
+  return [...map.values()];
+}
+
+function uniqueStrings(values) {
+  const out = [];
+  const seen = new Set();
+  for (const value of values) {
+    const text = String(value || "").trim();
+    if (!text) continue;
+    const key = text.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(text);
+  }
+  return out;
+}
+
+function emailValidationError(email) {
+  const text = String(email || "").trim();
+  if (!text) return "email is required.";
+  const parts = text.split("@");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return `Invalid email address: ${text}`;
+  if (text.length > 254 || /\s/.test(text)) return `Invalid email address: ${text}`;
+  const domain = parts[1].toLowerCase();
+  const labels = domain.split(".");
+  if (labels.length < 2) return `Invalid email domain: ${domain}`;
+  for (const label of labels) {
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label)) return `Invalid email domain: ${domain}`;
+  }
+  const tld = labels.at(-1);
+  if (!/^[a-z]{2,63}$/i.test(tld) || RESERVED_EMAIL_TLDS.has(tld)) return `Unsupported email domain: ${domain}`;
+  return null;
+}
+
+function uniquePersons(values) {
+  const out = [];
+  const seen = new Set();
+  for (const value of values) {
+    if (!value || typeof value !== "object") continue;
+    const person = cleanObject({
+      linkedin_url: cleanString(value.linkedin_url || value.linkedin),
+      company_url: cleanString(value.company_url || value.domain || value.company_domain || value.url),
+      first_name: cleanString(value.first_name || value.firstName),
+      last_name: cleanString(value.last_name || value.lastName),
+    });
+    if (!person.linkedin_url && !(person.company_url && person.first_name && person.last_name)) continue;
+    const key = `${person.linkedin_url || ""}|${person.company_url || ""}|${person.first_name || ""}|${person.last_name || ""}`.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(person);
+  }
+  return out;
+}
+
+function createResumeTracker(state, items, keyFn, options = {}) {
+  const completed = new Set(arrayOfStrings(state?.completed).map((key) => key.toLowerCase()));
+  const failed = new Set(arrayOfStrings(state?.failed).map((key) => key.toLowerCase()));
+  const skipped = new Set(arrayOfStrings(state?.skipped).map((key) => key.toLowerCase()));
+  const keyFor = (item) => String(keyFn(item) || "").toLowerCase();
+  const pendingItems = [];
+  for (const item of items) {
+    const key = keyFor(item);
+    if (!key || completed.has(key) || failed.has(key) || skipped.has(key)) continue;
+    pendingItems.push(item);
+  }
+  const tracker = {
+    items: pendingItems,
+    complete(item) {
+      const key = keyFor(item);
+      if (key) completed.add(key);
+      notify();
+    },
+    fail(item) {
+      const key = keyFor(item);
+      if (key) failed.add(key);
+      notify();
+    },
+    skip(item) {
+      const key = keyFor(item);
+      if (key) skipped.add(key);
+      notify();
+    },
+    summary() {
+      const pending = items.map(keyFor).filter((key) => key && !completed.has(key) && !failed.has(key) && !skipped.has(key));
+      return {
+        completed: [...completed],
+        failed: [...failed],
+        ...(skipped.size ? { skipped: [...skipped] } : {}),
+        pending,
+        inputCount: items.length,
+        pendingCount: pending.length,
+      };
+    },
+  };
+  function notify() {
+    if (typeof options.onChange === "function") options.onChange(tracker.summary());
+  }
+  return tracker;
+}
+
+function personKey(person) {
+  return (
+    person.linkedin_url ||
+    [person.company_url, person.first_name, person.last_name].filter(Boolean).join("|")
+  ).toLowerCase();
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function leadKey(lead) {
+  return (
+    lead.employee_linkedin ||
+    lead.email ||
+    [lead.first_name, lead.last_name, lead.company_url || lead.batch_company_url || lead.company_name].filter(Boolean).join("|").toLowerCase() ||
+    JSON.stringify(lead)
+  );
+}
+
+async function withConcurrency(items, concurrency, worker) {
+  if (!items.length) return [];
+  const limit = Math.min(concurrency, items.length);
+  if (limit >= items.length) {
+    return Promise.all(items.map((item, index) => worker(item, index)));
+  }
+  const output = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: limit }, async () => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      output[index] = await worker(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return output;
+}
+
+async function requestJsonFetch({ fetchImpl, url, method, headers, payload, signal }) {
+  const response = await fetchImpl(url, {
+    method,
+    headers,
+    body: payload,
+    signal,
+  });
+  const parsed = await parseFetchResponse(response);
+  return {
+    ok: response.ok,
+    status: response.status,
+    data: parsed.data,
+    headers: response.headers,
+  };
+}
+
+function requestJsonNative({ target, method, headers, payload, timeoutMs, httpAgent, httpsAgent }) {
+  const transport = target.protocol === "http:" ? httpRequest : httpsRequest;
+  const agent = target.protocol === "http:" ? httpAgent : httpsAgent;
+  return new Promise((resolve, reject) => {
+    const req = transport(target, { method, headers, agent }, (res) => {
+      let text = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        text += chunk;
+      });
+      res.on("end", () => {
+        resolve({
+          ok: Number(res.statusCode) >= 200 && Number(res.statusCode) < 300,
+          status: Number(res.statusCode || 0),
+          data: parseJsonText(text),
+          headers: res.headers,
+        });
+      });
+    });
+    req.setTimeout(timeoutMs, () => {
+      const error = new Error(`Quick Enrich request timed out after ${timeoutMs}ms`);
+      error.name = "AbortError";
+      req.destroy(error);
+    });
+    req.on("error", reject);
+    if (payload !== undefined) req.write(payload);
+    req.end();
+  });
+}
+
+async function parseFetchResponse(response) {
+  const text = await response.text();
+  return { data: parseJsonText(text) };
+}
+
+function parseJsonText(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { text };
+  }
+}
+
+function rateLimitHeaders(headers) {
+  return cleanObject({
+    limit: headerValue(headers, "x-ratelimit-limit"),
+    remaining: headerValue(headers, "x-ratelimit-remaining"),
+    reset: headerValue(headers, "x-ratelimit-reset"),
+    retryAfter: headerValue(headers, "retry-after"),
+  });
+}
+
+function headerValue(headers, key) {
+  if (!headers) return undefined;
+  if (typeof headers.get === "function") return headers.get(key) || undefined;
+  const value = headers[key.toLowerCase()] ?? headers[key];
+  return Array.isArray(value) ? value.join(", ") : value;
+}
+
+function retryAfterMs(error) {
+  const retryAfter = Number(error?.result?.rateLimit?.retryAfter);
+  return Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 0;
+}
+
+export function compactToolPayload(payload, options = {}) {
+  const resolved = responseOptions(options);
+  const meta = { truncated: false, paths: [] };
+  const compacted = compactValue(redact(payload), resolved, "$", 0, meta);
+  const output = cleanObject({
+    ...compacted,
+    _meta: cleanObject({
+      responseMode: resolved.mode,
+      truncated: meta.truncated || undefined,
+      truncatedPaths: meta.paths.length ? meta.paths.slice(0, 50) : undefined,
+    }),
+  });
+  const text = JSON.stringify(output);
+  if (Buffer.byteLength(text, "utf8") <= resolved.maxOutputChars) return attachSerializedToolPayload(output, text);
+  const omitted = {
+    ok: Boolean(payload?.ok),
+    omitted: true,
+    bytes: Buffer.byteLength(text, "utf8"),
+    hint: "Output exceeded maxOutputChars. Use response:{mode:'meta'} or lower limits.",
+    summary: summarizeValue(payload),
+  };
+  return attachSerializedToolPayload(omitted, JSON.stringify(omitted));
+}
+
+export function toolPayloadText(payload, pretty = false) {
+  if (!pretty && payload && typeof payload === "object" && typeof payload[SERIALIZED_TOOL_PAYLOAD] === "string") {
+    return payload[SERIALIZED_TOOL_PAYLOAD];
+  }
+  return JSON.stringify(payload, null, pretty ? 2 : 0);
+}
+
+function attachSerializedToolPayload(payload, text) {
+  if (!payload || typeof payload !== "object") return payload;
+  Object.defineProperty(payload, SERIALIZED_TOOL_PAYLOAD, {
+    value: text,
+    enumerable: false,
+    configurable: false,
+  });
+  return payload;
+}
+
+export function responseOptions(options = {}) {
+  const source = options && typeof options === "object" ? options : {};
+  const mode = RESPONSE_MODES.has(source.mode) ? source.mode : RESPONSE_MODES.has(DEFAULT_RESPONSE_MODE) ? DEFAULT_RESPONSE_MODE : "compact";
+  return {
+    mode,
+    maxItems: positiveInteger(source.maxItems, 12),
+    maxKeys: positiveInteger(source.maxKeys, 48),
+    maxDepth: positiveInteger(source.maxDepth, 4),
+    maxStringChars: positiveInteger(source.maxStringChars, 240),
+    maxOutputChars: positiveInteger(source.maxOutputChars, MAX_OUTPUT_CHARS),
+  };
+}
+
+export function compactValue(value, options, path = "$", depth = 0, meta = { truncated: false, paths: [] }) {
+  if (options.mode === "full") return value;
+  if (options.mode === "meta") return summarizeValue(value);
+  if (typeof value === "string") {
+    if (value.length <= options.maxStringChars) return value;
+    meta.truncated = true;
+    meta.paths.push(path);
+    return `${value.slice(0, options.maxStringChars)}...`;
+  }
+  if (!value || typeof value !== "object") return value;
+  if (depth >= options.maxDepth) {
+    meta.truncated = true;
+    meta.paths.push(path);
+    return summarizeValue(value);
+  }
+  if (Array.isArray(value)) {
+    const max = Math.min(value.length, options.maxItems);
+    const out = new Array(max);
+    for (let index = 0; index < max; index += 1) {
+      out[index] = compactValue(value[index], options, `${path}[${index}]`, depth + 1, meta);
+    }
+    if (value.length > options.maxItems) {
+      meta.truncated = true;
+      meta.paths.push(`${path}[${options.maxItems}..]`);
+      out.push({ omitted: value.length - options.maxItems });
+    }
+    return out;
+  }
+  const out = {};
+  const keys = Object.keys(value);
+  let written = 0;
+  let omitted = 0;
+  for (const key of keys) {
+    const entry = value[key];
+    if (entry === undefined) continue;
+    if (written >= options.maxKeys) {
+      omitted += 1;
+      continue;
+    }
+    out[key] = compactValue(entry, options, `${path}.${key}`, depth + 1, meta);
+    written += 1;
+  }
+  if (omitted) {
+    meta.truncated = true;
+    meta.paths.push(`${path}.{${options.maxKeys}..}`);
+    out._omittedKeys = omitted;
+  }
+  return out;
+}
+
+export function summarizeValue(value) {
+  if (Array.isArray(value)) return { type: "array", length: value.length };
+  if (value && typeof value === "object") {
+    const scalars = {};
+    const collections = {};
+    let collectionCount = 0;
+    for (const [key, entry] of Object.entries(value)) {
+      if (entry === undefined) continue;
+      if (entry === null || typeof entry === "boolean" || typeof entry === "number") {
+        scalars[key] = entry;
+      } else if (typeof entry === "string") {
+        scalars[key] = entry.length <= 160 ? entry : `${entry.slice(0, 160)}...`;
+      } else if (collectionCount < 16 && Array.isArray(entry)) {
+        collections[key] = { type: "array", length: entry.length };
+        collectionCount += 1;
+      } else if (collectionCount < 16 && entry && typeof entry === "object") {
+        collections[key] = { type: "object", keys: Object.keys(entry).slice(0, 8) };
+        collectionCount += 1;
+      }
+    }
+    return cleanObject({
+      type: "object",
+      keys: Object.keys(value).slice(0, 16),
+      scalars: Object.keys(scalars).length ? scalars : undefined,
+      collections: Object.keys(collections).length ? collections : undefined,
+    });
+  }
+  if (typeof value === "string") return { type: "string", length: value.length };
+  return value;
+}
+
+export function redact(value) {
+  if (typeof value === "string") {
+    if (!couldContainSecret(value)) return value;
+    return value
+      .replace(/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer <redacted>")
+      .replace(/([?&](?:secret|token|api[_-]?key|password)=)[^&\s"]+/gi, "$1<redacted>");
+  }
+  if (Array.isArray(value)) {
+    let out;
+    for (let index = 0; index < value.length; index += 1) {
+      const entry = value[index];
+      const redacted = redact(entry);
+      if (redacted !== entry) {
+        if (!out) out = value.slice(0, index);
+        out.push(redacted);
+      } else if (out) {
+        out.push(entry);
+      }
+    }
+    return out || value;
+  }
+  if (value && typeof value === "object") {
+    let out;
+    for (const key of Object.keys(value)) {
+      const entry = value[key];
+      const redacted = /api[_-]?key|authorization|password|secret|token/i.test(key) ? "<redacted>" : redact(entry);
+      if (redacted !== entry) {
+        if (!out) out = { ...value };
+        out[key] = redacted;
+      }
+    }
+    return out || value;
+  }
+  return value;
+}
+
+function couldContainSecret(value) {
+  const text = String(value);
+  return text.includes("?")
+    || text.includes("&")
+    || /bearer|secret|token|api[_-]?key|password/i.test(text);
+}
+
+export function cleanObject(value) {
+  const out = {};
+  for (const key of Object.keys(value || {})) {
+    const entry = value[key];
+    if (entry !== undefined && entry !== null && entry !== "") out[key] = entry;
+  }
+  return out;
+}
+
+function normalizePhone(value) {
+  const raw = String(value || "").trim();
+  if (!raw || /^(n\/a|na|none|null|-|unknown)$/i.test(raw)) return "";
+  const digits = raw.replace(/[^\d+]/g, "");
+  if (!digits) return "";
+  if (digits.startsWith("+")) return digits;
+  if (digits.length === 10) return `+1${digits}`;
+  return `+${digits}`;
+}
+
+function boolOrUndefined(value) {
+  if (typeof value === "boolean") return value;
+  return undefined;
+}
+
+function cleanString(value) {
+  const text = String(value || "").trim();
+  return /^(n\/a|na|none|null|-|unknown)$/i.test(text) ? "" : text;
+}
+
+function arrayOfStrings(value) {
+  const values = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+  return values.map(cleanString).filter(Boolean);
+}
+
+function booleanQuery(value) {
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return undefined;
+}
+
+function recordsFromTextInputs(args) {
+  return [
+    ...parseFileRecords(args.input_file, args.input_format),
+    ...parseCsvRecords(args.input_csv),
+    ...parseJsonlRecords(args.input_jsonl),
+  ];
+}
+
+function parseFileRecords(path, explicitFormat) {
+  if (!path) return [];
+  const filePath = localFilePath(path);
+  const text = readFileSync(filePath, "utf8");
+  const format = String(explicitFormat || extname(filePath).replace(/^\./, "") || "").toLowerCase();
+  if (format === "jsonl" || format === "ndjson") return parseJsonlRecords(text);
+  if (format === "csv") return parseCsvRecords(text);
+  const trimmed = text.trimStart();
+  if (trimmed.startsWith("{")) return parseJsonlRecords(text);
+  return parseCsvRecords(text);
+}
+
+function localFilePath(value) {
+  const raw = String(value || "").trim();
+  if (!raw) throw new Error("file path is required.");
+  if (raw.startsWith("file://")) return new URL(raw).pathname;
+  return raw;
+}
+
+function prepareBulkArgs(args = {}) {
+  const out = { ...(args && typeof args === "object" ? args : {}) };
+  if (out.resume_file) {
+    out.resume_file = localFilePath(out.resume_file);
+    out.resume_state = mergeResumeStates(readJsonFile(out.resume_file) || {}, out.resume_state || {});
+  }
+  if (out.output_file) out.output_file = localFilePath(out.output_file);
+  return out;
+}
+
+function mergeResumeStates(fileState, inlineState) {
+  const file = fileState && typeof fileState === "object" ? fileState : {};
+  const inline = inlineState && typeof inlineState === "object" ? inlineState : {};
+  return cleanObject({
+    ...file,
+    ...inline,
+    completed: uniqueStrings([...arrayOfStrings(file.completed), ...arrayOfStrings(inline.completed)]),
+    failed: uniqueStrings([...arrayOfStrings(file.failed), ...arrayOfStrings(inline.failed)]),
+    skipped: uniqueStrings([...arrayOfStrings(file.skipped), ...arrayOfStrings(inline.skipped)]),
+  });
+}
+
+function resumeTrackerOptions(args) {
+  if (!args?.resume_file) return {};
+  return {
+    onChange(summary) {
+      writeJsonFileAtomic(args.resume_file, summary);
+    },
+  };
+}
+
+function writeJsonFileAtomic(path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmpPath = tempArtifactPath(path);
+  writeFileSync(tmpPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmpPath, path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Best-effort when the filesystem does not support chmod.
+  }
+}
+
+function writeRowsFile(path, rows, format) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const exported = formatExport(rows, format);
+  const text = exported?.text || "";
+  const tmpPath = tempArtifactPath(path);
+  writeFileSync(tmpPath, text && !text.endsWith("\n") ? `${text}\n` : text, { mode: 0o600 });
+  renameSync(tmpPath, path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Best-effort only.
+  }
+  return {
+    path,
+    format,
+    count: exported?.count || 0,
+    bytes: Buffer.byteLength(text, "utf8"),
+  };
+}
+
+function tempArtifactPath(path) {
+  artifactWriteCounter = (artifactWriteCounter + 1) % 1_000_000_000;
+  return `${path}.${process.pid}.${Date.now()}.${artifactWriteCounter}.tmp`;
+}
+
+function parseJsonlRecords(text) {
+  return String(text || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function parseCsvRecords(text) {
+  const lines = String(text || "").split(/\r?\n/).filter((line) => line.trim());
+  if (lines.length < 2) return [];
+  const headers = parseCsvLine(lines[0]).map((header) => header.trim());
+  return lines.slice(1).map((line) => {
+    const values = parseCsvLine(line);
+    const row = {};
+    headers.forEach((header, index) => {
+      row[header] = values[index] || "";
+    });
+    return row;
+  });
+}
+
+function parseCsvLine(line) {
+  const text = String(line || "");
+  if (!text.includes('"')) return text.split(",");
+  const out = [];
+  let value = "";
+  let quoted = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '"' && text[index + 1] === '"') {
+      value += '"';
+      index += 1;
+    } else if (char === '"') {
+      quoted = !quoted;
+    } else if (char === "," && !quoted) {
+      out.push(value);
+      value = "";
+    } else {
+      value += char;
+    }
+  }
+  out.push(value);
+  return out;
+}
+
+function exportFormatOption(value) {
+  const format = String(value || "none").toLowerCase();
+  return ["jsonl", "csv"].includes(format) ? format : "none";
+}
+
+function formatExport(rows, format) {
+  if (!format || format === "none") return undefined;
+  const list = Array.isArray(rows) ? rows : [];
+  if (format === "jsonl") {
+    return { format, count: list.length, text: list.map((row) => JSON.stringify(cleanObject(row))).join("\n") };
+  }
+  return { format, count: list.length, text: toCsv(list) };
+}
+
+function toCsv(rows) {
+  const flatRows = new Array(rows.length);
+  const headers = [];
+  const seenHeaders = new Set();
+  rows.forEach((row, index) => {
+    const flat = flatExportRow(row);
+    flatRows[index] = flat;
+    for (const header of Object.keys(flat)) {
+      if (seenHeaders.has(header)) continue;
+      seenHeaders.add(header);
+      headers.push(header);
+    }
+  });
+  const lines = [headers.join(",")];
+  for (const flat of flatRows) {
+    lines.push(headers.map((header) => csvCell(flat[header])).join(","));
+  }
+  return lines.join("\n");
+}
+
+function flatExportRow(row) {
+  const out = {};
+  for (const [key, value] of Object.entries(row || {})) {
+    if (value === undefined || value === null) continue;
+    out[key] = Array.isArray(value) ? value.join(";") : typeof value === "object" ? JSON.stringify(value) : value;
+  }
+  return out;
+}
+
+function csvCell(value) {
+  const text = String(value ?? "");
+  return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+function projectionMode(args = {}) {
+  const mode = String(args.projection || "full").toLowerCase();
+  return PROJECTION_MODES.has(mode) ? mode : "full";
+}
+
+function projectRows(rows, projection, endpoint) {
+  const list = Array.isArray(rows) ? rows : [];
+  if (projection === "full") return list;
+  return list.map((row) => projectRow(row, projection, endpoint));
+}
+
+function projectRow(row, projection, endpoint) {
+  const quality = qualityFor(row, endpoint);
+  if (projection === "emails") {
+    return cleanObject({
+      email: row.email,
+      found: row.found,
+      first_name: row.first_name,
+      last_name: row.last_name,
+      name: row.name,
+      company_url: row.company_url || row.batch_company_url,
+      company_name: row.company_name,
+      quality,
+    });
+  }
+  if (projection === "phones") {
+    return cleanObject({
+      phone: row.phone,
+      company_phone: row.company_phone,
+      found: row.found,
+      first_name: row.first_name,
+      last_name: row.last_name,
+      name: row.name,
+      company_url: row.company_url || row.batch_company_url,
+      company_name: row.company_name,
+      quality,
+    });
+  }
+  if (projection === "ids") {
+    return cleanObject({
+      email: row.email,
+      phone: row.phone,
+      employee_linkedin: row.employee_linkedin,
+      linkedin_url: row.linkedin_url,
+      company_url: row.company_url || row.batch_company_url,
+      domain: row.domain,
+      company_name: row.company_name,
+      quality,
+    });
+  }
+  if (projection === "companies") {
+    return cleanObject({
+      company_name: row.company_name,
+      domain: row.domain || normalizeDomainKey(row.company_url || row.batch_company_url || row.url),
+      url: row.url || row.company_url || row.batch_company_url,
+      email_domain: row.email_domain,
+      linkedin_url: row.linkedin_url,
+      country_code: row.country_code,
+      industry: row.industry,
+      employee_count: row.employee_count,
+      revenue: row.revenue,
+      services: row.services,
+      quality,
+    });
+  }
+  return cleanObject({
+    first_name: row.first_name,
+    last_name: row.last_name,
+    name: row.name,
+    title: row.title,
+    email: row.email,
+    phone: row.phone,
+    employee_linkedin: row.employee_linkedin,
+    company_url: row.company_url || row.batch_company_url,
+    company_name: row.company_name,
+    quality,
+  });
+}
+
+function qualityFor(row, endpoint) {
+  const found = row?.found === false
+    ? false
+    : Boolean(row?.email || row?.phone || row?.employee_linkedin || row?.linkedin_url || row?.domain || row?.company_url || row?.company_name);
+  return cleanObject({
+    match_status: found ? "matched" : "not_found",
+    source_endpoint: row?.source || endpoint,
+  });
+}
+
+function outputFormatFor(args, fallback = "jsonl") {
+  const explicit = exportFormatOption(args.export_format);
+  if (explicit !== "none") return explicit;
+  const ext = String(extname(args.output_file || "")).toLowerCase();
+  if (ext === ".csv") return "csv";
+  if (ext === ".jsonl" || ext === ".ndjson") return "jsonl";
+  return fallback;
+}
+
+function finalizeRowsResult(result, args, rowsKey, endpoint, exportRows = result?.[rowsKey] || []) {
+  const projection = projectionMode(args);
+  const inlineRows = projectRows(result?.[rowsKey] || [], projection, endpoint);
+  const artifactRows = projectRows(exportRows, projection, endpoint);
+  const out = { ...result };
+  if (rowsKey && Array.isArray(result?.[rowsKey])) out[rowsKey] = inlineRows;
+  if (args.output_file) out.output = writeRowsFile(args.output_file, artifactRows, outputFormatFor(args));
+  if (args.resume_file) out.resume = { path: args.resume_file, state: result.resumeState };
+  if (args.credit_ledger) out.ledger = appendCreditLedger(args, out);
+  return out;
+}
+
+function cacheOptions(args = {}) {
+  const mode = String(args.cache_mode || "off").toLowerCase();
+  const resolved = CACHE_MODES.has(mode) ? mode : "off";
+  return {
+    mode: resolved,
+    enabled: resolved !== "off",
+    canRead: resolved === "read" || resolved === "readwrite" || resolved === "cache_only",
+    canWrite: resolved === "write" || resolved === "readwrite" || resolved === "refresh",
+    refresh: resolved === "refresh",
+    cacheOnly: resolved === "cache_only",
+    dir: process.env.QUICKENRICH_MCP_CACHE_DIR || join(DEFAULT_DATA_DIR, "cache"),
+  };
+}
+
+function cacheKey(endpoint, payload) {
+  return createHash("sha1")
+    .update(stableStringify({ endpoint, payload }))
+    .digest("hex");
+}
+
+function cachePath(options, endpoint, payload) {
+  return join(options.dir, endpoint, `${cacheKey(endpoint, payload)}.json`);
+}
+
+function readCachedValue(options, endpoint, payload) {
+  if (!options.enabled || !options.canRead || options.refresh) return undefined;
+  const path = cachePath(options, endpoint, payload);
+  if (!existsSync(path)) return undefined;
+  try {
+    return readJsonFile(path)?.value;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeCachedValue(options, endpoint, payload, value) {
+  if (!options.enabled || !options.canWrite) return;
+  const path = cachePath(options, endpoint, payload);
+  writeJsonFileAtomic(path, { endpoint, payload, value, cachedAt: new Date().toISOString() });
+}
+
+function appendCreditLedger(args, result) {
+  const path = args.credit_ledger_path || process.env.QUICKENRICH_MCP_LEDGER_PATH || join(DEFAULT_DATA_DIR, "credits.jsonl");
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const entry = cleanObject({
+    at: new Date().toISOString(),
+    mode: result.mode,
+    endpoint: result.endpoint,
+    requestCount: result.requestCount,
+    creditsUsed: result.creditsUsed,
+    remainingCredits: result.remainingCredits,
+    inputCount: result.inputCount ?? result.inputCompanyCount,
+    foundCount: result.foundCount,
+    leadCount: result.leadCount,
+    companyCount: result.companyCount,
+    cache: result.cache,
+  });
+  appendFileSync(path, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Best-effort.
+  }
+  return { path, entries: 1 };
+}
+
+function createCreditBudget(maxCredits) {
+  const max = Number(maxCredits);
+  const limited = Number.isFinite(max) && max >= 0;
+  let used = 0;
+  let reserved = 0;
+  let stopped = false;
+
+  function asNumber(value, fallback = 0) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) && numeric >= 0 ? Math.floor(numeric) : fallback;
+  }
+
+  function normalizeEstimate(value) {
+    return asNumber(value, 1);
+  }
+
+  return {
+    limited,
+    canStart(estimate = 1) {
+      if (!limited) return true;
+      const requested = normalizeEstimate(estimate);
+      if (used + reserved + requested > max) {
+        stopped = true;
+        return false;
+      }
+      return true;
+    },
+    tryReserve(estimate = 1) {
+      if (!limited) return true;
+      const requested = normalizeEstimate(estimate);
+      if (used + reserved + requested > max) {
+        stopped = true;
+        return false;
+      }
+      reserved += requested;
+      return true;
+    },
+    commit(consumed = 0, estimate = 0) {
+      if (!limited) return;
+      const committed = normalizeEstimate(estimate);
+      const spend = asNumber(consumed, 0);
+      reserved = Math.max(0, reserved - committed);
+      if (spend > 0) {
+        used = Math.min(max, used + spend);
+      }
+      if (used >= max) stopped = true;
+    },
+    release(estimate = 0) {
+      if (!limited) return;
+      const released = asNumber(estimate, 0);
+      reserved = Math.max(0, reserved - released);
+    },
+    record(credits) {
+      const value = Number(credits || 0);
+      if (Number.isFinite(value) && value > 0) {
+        used = Math.min(max, used + value);
+      }
+      if (limited && used >= max) stopped = true;
+    },
+    remaining() {
+      if (!limited) return Number.POSITIVE_INFINITY;
+      return Math.max(0, max - used - reserved);
+    },
+    summary() {
+      return cleanObject({
+        maxCredits: limited ? max : undefined,
+        used,
+        reserved,
+        remaining: limited ? Math.max(0, max - used - reserved) : undefined,
+        stopped: stopped || undefined,
+      });
+    },
+  };
+}
+
+function numericMeta(value, fallback) {
+  const number = Number(value);
+  if (Number.isFinite(number)) return number;
+  return fallback;
+}
+
+function minDefined(values) {
+  const nums = values.filter((value) => Number.isFinite(Number(value))).map(Number);
+  return nums.length ? Math.min(...nums) : undefined;
+}
+
+export function positiveInteger(value, fallback) {
+  const number = Number(value);
+  const fallbackNumber = Number(fallback);
+  const safeFallback = Number.isFinite(fallbackNumber) && fallbackNumber > 0 ? Math.floor(fallbackNumber) : 1;
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : safeFallback;
+}
+
+function clampInt(value, min, max, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(number)));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}