@sellable/mcp 0.1.0

package/dist/tools/leads.js

@@ -0,0 +1,2307 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { getApi, SellableApiError } from "../api.js";
+import { resolveWorkspaceRoot } from "../utils/workspace-root.js";
+import { buildCsvDomainPreview, matchesConfirmationToken, parseConfirmationToken, projectCsvCarryRows, } from "./csv-domains.js";
+import { buildCsvLinkedinPreview, matchesLinkedinConfirmationToken, parseLinkedinConfirmationToken, uploadCsvLinkedinFile, } from "./csv-linkedin.js";
+import { assertInteractionApproval } from "./interaction-mode.js";
+import { assertProviderPromptLoaded, markProviderPromptLoaded, } from "./provider-preflight.js";
+import { waitForLeadListReady } from "./readiness.js";
+const entryPath = process.argv[1] ? resolve(process.argv[1]) : process.cwd();
+const entryDir = dirname(entryPath);
+const workspaceRoot = resolveWorkspaceRoot(entryDir);
+const signalProviderConfigPath = join(workspaceRoot, "mcp/sellable/skills/create-campaign/core/providers/signal-discovery.json");
+const leadImportLimitsPath = join(workspaceRoot, "lead-import-limits.json");
+const defaultLeadImportLimits = {
+    apollo: { maxImportCount: 2500 },
+    "sales-nav": { maxImportCount: 2500 },
+    prospeo: { maxImportCount: 10000 },
+};
+const defaultSignalDiscoveryConfig = {
+    selection: {
+        promisingPostsTarget: 3,
+    },
+};
+const prospeoFilterValueSchema = {
+    type: "object",
+    description: "Include/exclude list filter (values must match Prospeo enums)",
+    properties: {
+        include: { type: "array", items: { type: "string" } },
+        exclude: { type: "array", items: { type: "string" } },
+    },
+};
+const prospeoRangeFilterSchema = {
+    type: "object",
+    description: "Numeric range filter (min/max)",
+    properties: {
+        min: { type: "number" },
+        max: { type: "number" },
+    },
+};
+const prospeoDateRangeFilterSchema = {
+    type: "object",
+    description: "Date range filter (YYYY-MM-DD)",
+    properties: {
+        min: { type: "string" },
+        max: { type: "string" },
+    },
+};
+const prospeoJobTitleSchema = {
+    type: "object",
+    description: "Job title filter (use include/exclude OR boolean_search, not both)",
+    properties: {
+        include: { type: "array", items: { type: "string" } },
+        exclude: { type: "array", items: { type: "string" } },
+        boolean_search: { type: "string" },
+        match_only_exact_job_titles: { type: "boolean" },
+    },
+};
+const prospeoContactDetailsSchema = {
+    type: "object",
+    description: "Contact details filter (email/mobile availability)",
+    properties: {
+        email: { type: "array", items: { type: "string" } },
+        mobile: { type: "array", items: { type: "string" } },
+        operator: { type: "string", enum: ["OR", "AND"] },
+        hide_people_with_details_already_revealed: { type: "boolean" },
+    },
+};
+const prospeoJobChangeSchema = {
+    type: "object",
+    description: "Recent job change filter",
+    properties: {
+        timeframe_days: { type: "number" },
+        only_promotion: { type: "boolean" },
+        only_new_company: { type: "boolean" },
+    },
+};
+const prospeoFundingAmountRangeSchema = {
+    type: "object",
+    description: "Funding amount range (<100K, 100K, 1M, 5M, etc.)",
+    properties: {
+        min: { type: "string" },
+        max: { type: "string" },
+    },
+};
+const prospeoFundingFilterSchema = {
+    type: "object",
+    description: "Company funding filters (stage array, funding_date days, last_funding/total_funding buckets)",
+    properties: {
+        stage: { type: "array", items: { type: "string" } },
+        funding_date: {
+            oneOf: [{ type: "number" }, prospeoDateRangeFilterSchema],
+            description: "Days since last funding (90/180/270/365)",
+        },
+        last_funding: prospeoFundingAmountRangeSchema,
+        total_funding: prospeoFundingAmountRangeSchema,
+        funding_stage: prospeoFilterValueSchema, // legacy
+        funding_amount: prospeoRangeFilterSchema, // legacy
+    },
+};
+const prospeoCompanyKeywordsSchema = {
+    type: "object",
+    description: "Company keyword search",
+    properties: {
+        include: { type: "array", items: { type: "string" } },
+        exclude: { type: "array", items: { type: "string" } },
+        include_all: { type: "boolean" },
+        include_company_description: { type: "boolean" },
+        include_company_description_seo: { type: "boolean" },
+    },
+};
+const prospeoCompanyAttributesSchema = {
+    type: "object",
+    description: "Company attributes (boolean flags)",
+    properties: {
+        b2b: { type: ["boolean", "null"] },
+        demo: { type: ["boolean", "null"] },
+        freetrial: { type: ["boolean", "null"] },
+        downloadable: { type: ["boolean", "null"] },
+        mobileapps: { type: ["boolean", "null"] },
+        onlinereviews: { type: ["boolean", "null"] },
+        pricing: { type: ["boolean", "null"] },
+    },
+};
+const prospeoCompanyRevenueSchema = {
+    type: "object",
+    description: "Company revenue range",
+    properties: {
+        min: { type: "string" },
+        max: { type: "string" },
+        include_unknown_revenue: { type: "boolean" },
+    },
+};
+const prospeoCompanyFoundedSchema = {
+    type: "object",
+    description: "Company founded year range",
+    properties: {
+        min: { type: "number" },
+        max: { type: "number" },
+        include_unknown_founded: { type: "boolean" },
+    },
+};
+const prospeoCompanyHeadcountGrowthSchema = {
+    type: "object",
+    description: "Company headcount growth",
+    properties: {
+        timeframe_month: { type: "number" },
+        min: { type: "number" },
+        max: { type: "number" },
+        departments: { type: "array", items: { type: "string" } },
+    },
+};
+const prospeoCompanyHeadcountByDepartmentSchema = {
+    type: "object",
+    description: "Headcount by department",
+    properties: {
+        department: { type: "string" },
+        min: { type: "number" },
+        max: { type: "number" },
+    },
+};
+function loadSignalDiscoveryConfig() {
+    if (!existsSync(signalProviderConfigPath)) {
+        return defaultSignalDiscoveryConfig;
+    }
+    try {
+        const raw = readFileSync(signalProviderConfigPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const selection = parsed.selection ?? {};
+        return {
+            selection: {
+                promisingPostsTarget: selection.promisingPostsTarget ??
+                    defaultSignalDiscoveryConfig.selection.promisingPostsTarget,
+            },
+        };
+    }
+    catch {
+        return defaultSignalDiscoveryConfig;
+    }
+}
+function parseApiErrorBody(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+}
+function loadLeadImportLimits() {
+    if (!existsSync(leadImportLimitsPath)) {
+        return defaultLeadImportLimits;
+    }
+    try {
+        const raw = readFileSync(leadImportLimitsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            ...defaultLeadImportLimits,
+            ...parsed,
+        };
+    }
+    catch {
+        return defaultLeadImportLimits;
+    }
+}
+function getMaxImportCount(provider) {
+    const limits = loadLeadImportLimits();
+    const max = limits[provider]?.maxImportCount;
+    if (typeof max === "number" && Number.isFinite(max) && max > 0) {
+        return max;
+    }
+    return defaultLeadImportLimits[provider].maxImportCount;
+}
+export function normalizeTargetLeadCount(targetLeadCount, maxImportCount) {
+    if (targetLeadCount === null || targetLeadCount === undefined) {
+        return undefined;
+    }
+    const numeric = typeof targetLeadCount === "number"
+        ? targetLeadCount
+        : Number(targetLeadCount);
+    if (!Number.isFinite(numeric) || numeric <= 0) {
+        return undefined;
+    }
+    return Math.min(numeric, maxImportCount);
+}
+function toDate(value) {
+    if (!value)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function recencyDays(postedAt) {
+    const date = toDate(postedAt);
+    if (!date)
+        return null;
+    const diffMs = Date.now() - date.getTime();
+    return Math.max(0, Math.floor(diffMs / (1000 * 60 * 60 * 24)));
+}
+function recencyWeight(days) {
+    if (days === null)
+        return 0.6;
+    // Use a fixed decay so "recent" stays first without extra config knobs.
+    const raw = Math.exp(-days / 30);
+    return Math.min(1, Math.max(0.3, raw));
+}
+function engagementScore(post) {
+    const likes = post.engagement?.likes ?? 0;
+    const comments = post.engagement?.comments ?? 0;
+    const shares = post.engagement?.shares ?? 0;
+    // Fixed weights: comments and shares signal stronger intent than likes.
+    return likes + comments * 2 + shares * 3;
+}
+function truncate(text, max = 220) {
+    if (!text)
+        return "";
+    const clean = text.replace(/\s+/g, " ").trim();
+    if (clean.length <= max)
+        return clean;
+    return `${clean.slice(0, max - 1)}...`;
+}
+function normalizePostUrl(url) {
+    if (!url)
+        return null;
+    try {
+        const parsed = new URL(url);
+        parsed.hash = "";
+        parsed.search = "";
+        return `${parsed.origin}${parsed.pathname}`.toLowerCase();
+    }
+    catch {
+        return url.trim().toLowerCase();
+    }
+}
+function rankSignalPosts(posts, config) {
+    void config;
+    return posts
+        .map((post) => {
+        const days = recencyDays(post.postedAt);
+        const recency = recencyWeight(days);
+        const engage = engagementScore(post);
+        const engageLog = Math.log1p(engage);
+        const aiScore = post.aiScore ?? 50;
+        const score = engageLog * 12 * recency + aiScore * 1.5;
+        return {
+            ...post,
+            _score: score,
+            _engagementScore: engage,
+            _recencyDays: days,
+            _recencyWeight: recency,
+        };
+    })
+        .sort((a, b) => b._score - a._score);
+}
+function summarizeSignalPost(post) {
+    const likes = post.engagement?.likes ?? 0;
+    const comments = post.engagement?.comments ?? 0;
+    const shares = post.engagement?.shares ?? 0;
+    return {
+        id: post.id,
+        url: post.url,
+        matchedKeyword: post.matchedKeyword ?? null,
+        authorName: post.author?.name ?? "",
+        authorHeadline: post.author?.headline ?? "",
+        authorProfileUrl: post.author?.profileUrl ?? "",
+        postedAt: post.postedAt ?? null,
+        recencyDays: post._recencyDays,
+        aiScore: post.aiScore ?? null,
+        engagement: {
+            likes,
+            comments,
+            shares,
+            weighted: post._engagementScore,
+        },
+        score: Number(post._score.toFixed(2)),
+        excerpt: truncate(post.content),
+    };
+}
+function summarizeSignalSearchResponse(response) {
+    const config = loadSignalDiscoveryConfig();
+    const posts = response.posts ?? [];
+    const ranked = rankSignalPosts(posts, config);
+    const selectionTarget = Math.max(1, config.selection.promisingPostsTarget);
+    const recommendedPostIds = ranked.slice(0, selectionTarget).map((p) => p.id);
+    // Include top posts preview so LLM can see content and make informed selections
+    const TOP_POSTS_PREVIEW_COUNT = 15;
+    const topPosts = ranked
+        .slice(0, TOP_POSTS_PREVIEW_COUNT)
+        .map(summarizeSignalPost);
+    const keywordResults = (response.keywordResults ?? []).map((kw) => ({
+        keyword: kw.keyword,
+        postCount: kw.postCount,
+        avgEngagement: kw.avgEngagement ?? null,
+        hasMore: kw.hasMore ?? false,
+        error: kw.error ?? null,
+    }));
+    return {
+        success: response.success === true,
+        totalPosts: response.totalPosts ?? posts.length,
+        postsReturned: posts.length,
+        selectionTarget,
+        recommendedPostIds,
+        topPosts,
+        keywordResults,
+        notes: [
+            `Showing top ${topPosts.length} posts by score. Review excerpts to pick the best ones.`,
+            `Select about ${selectionTarget} posts, then call select_promising_posts.`,
+        ],
+    };
+}
+export const leadToolDefinitions = [
+    {
+        name: "get_provider_prompt",
+        description: "Get the search instructions for a lead source provider and register provider prompt preflight readiness. Must be called before provider search/import tools.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: {
+                    type: "string",
+                    enum: ["apollo", "sales-nav", "prospeo", "signal-discovery"],
+                    description: "Provider to get instructions for: apollo, sales-nav, prospeo, or signal-discovery",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Optional campaign offer ID for campaign-scoped preflight tracking.",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true after user approval when interaction mode requires confirmation for this action.",
+                },
+            },
+            required: ["provider"],
+        },
+    },
+    {
+        name: "search_apollo",
+        description: "Search Apollo for people/contacts. Requires get_provider_prompt({ provider: \"apollo\" }) first. Supports two modes: 'people' (default) searches contacts directly, 'combined' (RECOMMENDED for B2B) first finds companies then contacts at those companies. Auto-detects combined mode when company filters are provided.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                searchMode: {
+                    type: "string",
+                    enum: ["people", "combined"],
+                    description: "Search mode: 'people' for direct contact search, 'combined' (auto-detected when company filters present) to find companies first then contacts. Combined is RECOMMENDED for B2B lead generation.",
+                },
+                // ============ COMPANY FILTERS (for combined search) ============
+                // These filters will auto-trigger combined mode if provided in filters object
+                organization_num_employees_ranges: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Employee count ranges. IMPORTANT: Use ONLY these exact valid ranges: '1,10' (1-10 employees), '11,50' (11-50), '51,200' (51-200), '201,500' (201-500), '501,1000' (501-1000), '1001,5000' (1001-5000), '5001,10000' (5001-10000), '10000+' (10000+). Combine multiple: ['11,50', '51,200'] for 11-200 employees.",
+                },
+                organization_locations: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Company HQ locations. Can be cities, US states, or countries. Examples: ['texas', 'tokyo', 'spain']",
+                },
+                organization_not_locations: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Locations to exclude. Examples: ['minnesota', 'ireland', 'seoul']",
+                },
+                q_organization_keyword_tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Keywords associated with companies. Examples: ['mining', 'sales strategy', 'consulting']. IMPORTANT: Use this instead of q_keywords when doing combined search - q_keywords doesn't work in combined mode.",
+                },
+                organization_industry_tag_ids: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Apollo industry tag IDs to filter companies by.",
+                },
+                // ============ FUNDING FILTERS (triggers combined mode) ============
+                latest_funding_amount_min: {
+                    type: "number",
+                    description: "**Use for Series A/B/C filtering**. Minimum amount raised in MOST RECENT round (integer). TYPICAL RANGES BY STAGE:\n- Seed: $500K-$2M → use 500000\n- Series A: $2M-$15M → use 2000000\n- Series B: $15M-$50M → use 15000000\n- Series C+: $50M+ → use 50000000\nExample: For 'Series A companies', use 2000000",
+                },
+                latest_funding_amount_max: {
+                    type: "number",
+                    description: "Maximum amount raised in MOST RECENT round (integer). Use to cap funding stage:\n- Seed max: 2000000\n- Series A max: 15000000\n- Series B max: 50000000\nExample: For 'Series A only', use min: 2000000, max: 15000000",
+                },
+                // ============ REVENUE FILTERS (triggers combined mode) ============
+                organization_revenue_min: {
+                    type: "number",
+                    description: "**Use for ARR/revenue filtering**. Minimum annual revenue (integer only). Examples: 1000000 for '$1M ARR', 10000000 for '$10M+ revenue'. Use when user mentions ARR, revenue, or revenue thresholds.",
+                },
+                organization_revenue_max: {
+                    type: "number",
+                    description: "Maximum annual revenue (integer only). ONLY use if user explicitly wants to exclude larger companies (e.g., 'under $50M revenue'). Omit unless user specifies upper limit.",
+                },
+                // ============ CONTACT/PERSON FILTERS ============
+                person_titles: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Job titles to find. Results include similar titles by default. Examples: ['sales development representative', 'marketing manager', 'cto']. For precision, provide comprehensive title variations.",
+                },
+                person_seniorities: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Seniority levels (current position only). Valid options: ['owner', 'founder', 'c_suite', 'partner', 'vp', 'head', 'director', 'manager', 'senior', 'entry', 'intern']",
+                },
+                person_locations: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Where people live (not company HQ). Examples: ['california', 'ireland', 'chicago']",
+                },
+                include_similar_titles: {
+                    type: "boolean",
+                    description: "Set to FALSE for precision with comprehensive title list, TRUE for Apollo's fuzzy matching. Default: FALSE.",
+                },
+                q_keywords: {
+                    type: "string",
+                    description: "GOTCHA: Only works in 'people' mode. In combined search, this is auto-converted to q_organization_keyword_tags. For combined searches, use q_organization_keyword_tags directly instead.",
+                },
+                // ============ LEGACY NESTED FILTERS (still supported) ============
+                filters: {
+                    type: "object",
+                    description: "Alternative: pass all filters in a single object. Company filters will auto-trigger combined mode. Prefer flat parameters above for clarity.",
+                },
+                companyFilters: {
+                    type: "object",
+                    description: "Explicit company filters object for combined mode (alternative to flat params).",
+                },
+                contactFilters: {
+                    type: "object",
+                    description: "Explicit contact filters object for combined mode (alternative to flat params).",
+                },
+                // ============ PAGINATION & CONTEXT ============
+                page: {
+                    type: "number",
+                    description: "Page number (default 1)",
+                },
+                searchId: {
+                    type: "string",
+                    description: "Existing Apollo search ID for pagination",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID to associate search",
+                },
+                searchName: {
+                    type: "string",
+                    description: "REQUIRED: Descriptive name for this search. Include key filters. Examples: 'SaaS + Series A-B + 11-200 employees', 'Healthcare VPs + 51-500 employees'",
+                },
+                companySearchMode: {
+                    type: "string",
+                    description: "Domain search mode (ai | domainList)",
+                },
+                uploadedDomains: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Domains for domainList mode",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: 'Headless workflow step ID. If omitted while in lead sourcing, defaults to "confirm-lead-list". Pass null to skip auto-advance.',
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true after user approval when interaction mode requires confirmation for search.",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "lookup_sales_nav_filter",
+        description: "Look up filter IDs for Sales Navigator dynamic filters. MUST be called before using REGION, INDUSTRY, CURRENT_TITLE, CURRENT_COMPANY, SCHOOL, or TECHNOLOGIES filters. Returns matching options with IDs that can be used in search_sales_nav.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filterType: {
+                    type: "string",
+                    enum: [
+                        "REGION",
+                        "GEOGRAPHY",
+                        "HEADQUARTERS_LOCATION",
+                        "INDUSTRY",
+                        "CURRENT_TITLE",
+                        "PAST_TITLE",
+                        "CURRENT_COMPANY",
+                        "PAST_COMPANY",
+                        "SCHOOL",
+                    ],
+                    description: "Filter type to look up. Use REGION for geography (countries, states, cities).",
+                },
+                query: {
+                    type: "string",
+                    description: 'Search query for the filter (e.g., "United States", "Software", "CEO")',
+                },
+            },
+            required: ["filterType", "query"],
+        },
+    },
+    {
+        name: "search_sales_nav",
+        description: 'Search LinkedIn Sales Navigator. Requires get_provider_prompt({ provider: "sales-nav" }) first. Returns normalized results with pagination. `campaignOfferId` is optional for directional preview runs; include it only when the search should be associated with a campaign.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                filters: {
+                    type: "array",
+                    description: "Sales Nav filter array",
+                },
+                keywords: {
+                    type: "string",
+                    description: "Optional keywords",
+                },
+                page: {
+                    type: "number",
+                    description: "Page number (default 1)",
+                },
+                searchId: {
+                    type: "string",
+                    description: "Existing Sales Nav search ID for pagination",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID to associate search",
+                },
+                searchName: {
+                    type: "string",
+                    description: "Optional name for the search",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Headless workflow step ID",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true after user approval when interaction mode requires confirmation for search.",
+                },
+            },
+            required: ["filters"],
+        },
+    },
+    {
+        name: "load_csv_domains",
+        description: "Preview and confirm a CSV file that lives on disk, then create a Prospeo domainFilterId for account targeting. This is the CSV-on-disk path for known-account targeting. First call previews the file and returns a confirmationToken. Confirmed execution requires the preview-issued confirmationToken and then returns a domainFilterId you can pass into search_prospeo.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filePath: {
+                    type: "string",
+                    description: "Absolute path on the MCP host, or a workspace-relative path to the CSV file.",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Optional campaign offer ID. When provided, success output includes direct follow-up calls for get_provider_prompt and search_prospeo.",
+                },
+                domainColumn: {
+                    type: "string",
+                    description: "Optional CSV header to use as the domain column. Required when the preview cannot auto-detect a strong domain header.",
+                },
+                selectedColumns: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional carryover columns to preserve with the domain filter. Max 20. Cannot include the chosen domain column.",
+                },
+                confirmationToken: {
+                    type: "string",
+                    description: "Preview-issued token that binds file path, file metadata, domainColumn, and selectedColumns.",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true only when confirming the preview with the matching confirmationToken.",
+                },
+            },
+            required: ["filePath"],
+        },
+    },
+    {
+        name: "load_csv_linkedin_leads",
+        description: "Preview and confirm a CSV file that lives on disk, then create or append to a lead list using LinkedIn profile URLs. This is the person-CSV path. First call previews the file and returns a confirmationToken. Confirmed execution requires the preview-issued confirmationToken, uploads valid LinkedIn profile rows into a lead list, and does NOT use the 1000-domain Prospeo cap.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filePath: {
+                    type: "string",
+                    description: "Absolute path on the MCP host, or a workspace-relative path to the CSV file.",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Optional campaign offer ID. When provided, success output also updates selectedLeadListId so the campaign can review this list.",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Optional workflow step to persist when selectedLeadListId is updated on the campaign.",
+                },
+                leadListId: {
+                    type: "string",
+                    description: "Optional existing lead list ID. When omitted, a new lead list is created.",
+                },
+                leadListName: {
+                    type: "string",
+                    description: "Optional lead list name. Used when creating a new list and also passed through as the uploaded listName.",
+                },
+                linkedInColumn: {
+                    type: "string",
+                    description: "Optional CSV header to use as the LinkedIn URL column. Required when preview cannot auto-detect a single strong/profile-url column.",
+                },
+                selectedColumns: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional source columns to carry into the lead list. Max 20. LinkedIn URL is always preserved and should not be included here.",
+                },
+                confirmationToken: {
+                    type: "string",
+                    description: "Preview-issued token that binds file path, file metadata, linkedInColumn, and selectedColumns.",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true only when confirming the preview with the matching confirmationToken.",
+                },
+            },
+            required: ["filePath"],
+        },
+    },
+    {
+        name: "save_domain_filters",
+        description: "Save pasted or raw include/exclude domain lists for Prospeo search. Validates domains and returns a domainFilterId to pass into search_prospeo. Use load_csv_domains when the user already has a CSV file on disk. If the user provides company names, resolve names to official website domains first, then call this tool.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                include: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Company domains to include in search (e.g. ['stripe.com', 'notion.so']). Max 1000.",
+                },
+                exclude: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Company domains to exclude from search (e.g. ['competitor.com']). Max 1000.",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "search_prospeo",
+        description: 'Search Prospeo for people using filters and optional domainFilterId. Requires get_provider_prompt({ provider: "prospeo" }) first. When targeting known accounts, call load_csv_domains for CSV-on-disk workflows or save_domain_filters for pasted/raw domain lists, then pass domainFilterId. Raw domain inputs and company-name targeting are NOT supported in this MCP tool. Strategy: start with 2-3 high-signal filters (title/seniority + industry or domainFilterId + headcount), then tighten one filter at a time. For security, AppSec, SOC, RevOps, Demand Gen, and similar function-specific lanes, do not widen with bare seniority labels like "Head" or "Director" alone; pair them with explicit function-title keywords and inspect the sample for off-function `Head of X` leakage. Prefer person location over company HQ unless HQ is explicitly needed. `campaignOfferId` routing rule: OMIT campaignOfferId ONLY in pre-mint Phase 84 `find leads` discovery mode (validating ICP before the commit gate). In every other context — post-mint lead additions, operator-driven searches on a live campaign, any search where the intent is to persist results to a specific campaign — you MUST pass campaignOfferId so the search shows up in that campaign\'s Contact Search panel. Omitting campaignOfferId post-mint orphans the search from the UI. Returns normalized results with pagination.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                filters: {
+                    type: "object",
+                    description: "Prospeo search filters. Use include/exclude arrays for enum filters. For account targeting, use domainFilterId from load_csv_domains or save_domain_filters (do not send company.websites or company.names in MCP). Prefer comprehensive person_job_title include lists (synonyms + role variants) for role precision; use person_department + person_seniority as supporting constraints when title variance is high. In function-specific lanes, do not rely on bare `Head` / `Director` / `VP` widening without matching function keywords because Prospeo can leak off-function `Head of X` rows. Provide at least one filter or domainFilterId for new searches.",
+                    properties: {
+                        person_name: prospeoFilterValueSchema,
+                        person_name_or_job_title: {
+                            type: "string",
+                            description: "Quick search across name + job title",
+                        },
+                        person_job_title: prospeoJobTitleSchema,
+                        person_seniority: {
+                            ...prospeoFilterValueSchema,
+                            description: 'Seniority filter. EXACT values: "Founder/Owner", "C-Suite", "Partner", "Vice President", "Head", "Director", "Manager", "Senior", "Entry", "Intern". Common aliases like "VP", "Founder", "Owner" are auto-corrected server-side.',
+                        },
+                        person_department: {
+                            ...prospeoFilterValueSchema,
+                            description: 'Department filter. EXACT values: "C-Suite", "Product", "Engineering & Technical", "Design", "Education & Coaching", "Finance", "Human Resources", "Information Technology", "Legal", "Marketing", "Medical & Health", "Consulting", "Sales", "Operations". Common aliases like "Engineering", "IT", "HR" are auto-corrected server-side.',
+                        },
+                        person_year_of_experience: prospeoRangeFilterSchema,
+                        person_time_in_current_role: prospeoRangeFilterSchema,
+                        person_time_in_current_company: prospeoRangeFilterSchema,
+                        person_location_search: prospeoFilterValueSchema,
+                        person_contact_details: prospeoContactDetailsSchema,
+                        person_job_change: prospeoJobChangeSchema,
+                        max_person_per_company: { type: "number" },
+                        company_industry: {
+                            ...prospeoFilterValueSchema,
+                            description: 'Industry filter (345+ values). Common: "Software Development", "IT Services and IT Consulting", "Technology, Information and Internet", "Financial Services", "Marketing Services", "Advertising Services", "SaaS" is NOT valid — use "Software Development" or "Technology, Information and Internet". Case-insensitive matching applied server-side.',
+                        },
+                        company_technology: {
+                            ...prospeoFilterValueSchema,
+                            description: "Technology filter (2000+ values, max 20 per search). Common: React, Next.js, Node.js, Python, AWS, Google Cloud, HubSpot, Salesforce, Shopify, WordPress, etc. Case-sensitive — use exact names.",
+                        },
+                        company_email_provider: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: 'MX/email provider filter. Common: "Google Workspace", "Microsoft 365", "Zoho Mail", "ProtonMail".',
+                        },
+                        company_naics: prospeoFilterValueSchema,
+                        company_sics: prospeoFilterValueSchema,
+                        company_headcount_range: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: 'Employee count ranges. EXACT values: "1-10", "11-20", "21-50", "51-100", "101-200", "201-500", "501-1000", "1001-2000", "2001-5000", "5001-10000", "10000+". Common aliases like "1-50", "500+" are auto-expanded server-side.',
+                        },
+                        company_headcount_custom: prospeoRangeFilterSchema,
+                        company_location_search: prospeoFilterValueSchema,
+                        company_type: {
+                            type: "string",
+                            description: 'Company type. EXACT values: "Private", "Public", "Non profit", "Other". Aliases like "nonprofit", "NGO" are auto-corrected server-side.',
+                        },
+                        company_funding: {
+                            ...prospeoFundingFilterSchema,
+                            description: 'Funding filters. stage values: "Pre seed", "Seed", "Series A", "Series B", "Series C", "Series D", "Series E-J", "Grant", "Angel", "Private equity", "Debt financing", "Convertible note", etc. Aliases like "pre-seed", "PE" are auto-corrected. funding_date: 30/60/90/180/270/365 days. last_funding/total_funding: string buckets like "<100K", "1M", "10M".',
+                        },
+                        company_keywords: prospeoCompanyKeywordsSchema,
+                        company_attributes: prospeoCompanyAttributesSchema,
+                        company_revenue: prospeoCompanyRevenueSchema,
+                        company_founded: prospeoCompanyFoundedSchema,
+                        company_headcount_growth: prospeoCompanyHeadcountGrowthSchema,
+                        company_job_posting_hiring_for: {
+                            type: "array",
+                            items: { type: "string" },
+                        },
+                        company_job_posting_quantity: prospeoRangeFilterSchema,
+                        company_headcount_by_department: {
+                            type: "array",
+                            items: prospeoCompanyHeadcountByDepartmentSchema,
+                        },
+                    },
+                },
+                page: {
+                    type: "number",
+                    description: "Page number (default 1)",
+                },
+                searchId: {
+                    type: "string",
+                    description: "Existing Prospeo search ID for pagination",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID to associate search",
+                },
+                searchName: {
+                    type: "string",
+                    description: "Optional name for the search. Use descriptive names that encode ICP intent (e.g., 'Fintech Compliance Directors 201-1000 US').",
+                },
+                domainFilterId: {
+                    type: "string",
+                    description: "ID from save_domain_filters. The search route resolves include/exclude domains from this ID.",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Headless workflow step ID",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true after user approval when interaction mode requires confirmation for search.",
+                },
+            },
+            required: ["filters"],
+        },
+    },
+    {
+        name: "search_signals",
+        description: 'Search LinkedIn posts for signal discovery. Requires get_provider_prompt({ provider: "signal-discovery" }) first. Supports keyword search, profile posts, company posts, or a single post URL. Use campaignless preview mode for directional discovery; include `campaignOfferId` only when the search should persist into campaign state. Returns a compact summary with recommended posts to avoid context bloat.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    enum: ["keywords", "profile", "post", "company"],
+                    description: "Search mode: 'keywords' (default), 'profile' for a user's posts, 'post' for a single post URL, or 'company' for recent company posts.",
+                    default: "keywords",
+                },
+                keywords: {
+                    type: "array",
+                    description: "Keyword objects to search (when type='keywords')",
+                    items: {
+                        type: "object",
+                        properties: {
+                            keyword: { type: "string" },
+                            id: { type: "string" },
+                            confidence: { type: ["number", "string"] },
+                            page: { type: "number" },
+                        },
+                        required: ["keyword"],
+                    },
+                },
+                profileUrl: {
+                    type: "string",
+                    description: "LinkedIn profile URL (when type='profile')",
+                },
+                postUrl: {
+                    type: "string",
+                    description: "LinkedIn post URL (when type='post')",
+                },
+                companyUrl: {
+                    type: "string",
+                    description: "LinkedIn company URL (when type='company')",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID to associate search. Optional for directional preview runs.",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Headless workflow step ID",
+                },
+                page: {
+                    type: "number",
+                    description: "Page number (default 1). Used for keyword search.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max posts (default 25, max 50). Used for profile search.",
+                },
+                headlineICPCriteria: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional: Persist headline ICP criteria early so the UI can show filters if the user takes over mid-flow.",
+                },
+                rubricGuidelines: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Deprecated alias for headlineICPCriteria. Prefer headlineICPCriteria.",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true after user approval when interaction mode requires confirmation for search.",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "import_leads",
+        description: "Create/select a lead list and start the provider import job. Requires provider prompt preflight via get_provider_prompt for the active provider. Sets selectedLeadListId to the lead list so the user can review it. Does NOT import into the campaign table. After the user confirms the list, call confirm_lead_list.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                provider: {
+                    type: "string",
+                    enum: ["apollo", "sales-nav", "prospeo", "signal-discovery"],
+                    description: "Lead provider. Auto-detected from campaign.leadSourceProvider if not specified.",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Headless workflow step ID",
+                },
+                sourceLeadListId: {
+                    type: "string",
+                    description: "Existing lead list ID to import from (skips search import)",
+                },
+                searchId: {
+                    type: "string",
+                    description: "Search ID for apollo or sales-nav import",
+                },
+                targetLeadCount: {
+                    type: "number",
+                    description: "Target number of leads (max per provider from config)",
+                },
+                mode: {
+                    type: "string",
+                    enum: ["add", "replace"],
+                    description: "How to handle existing lead list rows. 'add' appends, 'replace' archives existing rows before import.",
+                },
+                searchName: {
+                    type: "string",
+                    description: "Name of the search (used for list naming)",
+                },
+                leadListName: {
+                    type: "string",
+                    description: "Override lead list name when creating a new one",
+                },
+                headlineICPCriteria: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Signal Discovery: headline ICP criteria (3-5 rules). Uses campaign.headlineICPCriteria if not provided.",
+                },
+                rubricGuidelines: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Deprecated alias for headlineICPCriteria. Prefer headlineICPCriteria.",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true after user approval when interaction mode requires confirmation for import.",
+                },
+            },
+            required: ["campaignOfferId"],
+        },
+    },
+    {
+        name: "cancel_lead_import",
+        description: "Cancel an in-flight Apollo, Prospeo, or Sales Nav lead import. Use when the operator realizes the current search/filter is wrong and wants to start over without waiting for the broad import to finish. Partial rows already inserted into the lead list are preserved. Provider credits are NOT refunded. After cancellation, call import_leads again with new filters. Signal Discovery cancellation is not supported.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID. Required for audit context; not used to resolve provider or tableId.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Lead list (workflow table) ID to cancel. Required; callers have this from campaign context.",
+                },
+                provider: {
+                    type: "string",
+                    enum: ["apollo", "prospeo", "sales-nav"],
+                    description: "Provider to cancel. Required; callers have this from campaign context. Signal Discovery is not supported.",
+                },
+            },
+            required: ["campaignOfferId", "tableId", "provider"],
+        },
+    },
+    {
+        name: "confirm_lead_list",
+        description: "After the user confirms the lead list looks good, import it into the campaign table (clone) and update selectedLeadListId to the campaign table. Recommended post-confirm order: update_campaign(currentStep='filter-choice') -> wait_for_campaign_table_ready -> get_rows_minimal.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                sourceLeadListId: {
+                    type: "string",
+                    description: "Lead list ID to import into campaign. If omitted, uses campaign.selectedLeadListId.",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: 'Headless workflow step ID. If omitted, defaults to "confirm-lead-list". Pass null to skip auto-advance.',
+                },
+                campaignName: {
+                    type: "string",
+                    description: "Optional campaign table name override",
+                },
+                keepInSync: {
+                    type: "boolean",
+                    description: "Keep campaign table synced to lead list",
+                },
+                jobId: {
+                    type: "string",
+                    description: "Import job ID (required for Sales Nav/Prospeo status checks).",
+                },
+                targetLeadCount: {
+                    type: "number",
+                    description: "Target lead count requested (used to validate completion when status is unavailable).",
+                },
+                confirmed: {
+                    type: "boolean",
+                    description: "Set true after user approval when interaction mode requires confirmation for confirm/import.",
+                },
+            },
+            required: ["campaignOfferId"],
+        },
+    },
+    {
+        name: "select_promising_posts",
+        description: "Select the most promising LinkedIn posts for lead scraping AND provide headline ICP criteria. Use the selectionTarget returned by search_signals (default 3).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                selections: {
+                    type: "array",
+                    description: "Array of promising posts to select for scraping. Prefer the recommendedPostIds from search_signals.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            postId: {
+                                type: "string",
+                                description: "The post ID from search_signals results",
+                            },
+                            reason: {
+                                type: "string",
+                                description: "Why this post is promising (content relevance, author credibility, engagement volume, recency)",
+                            },
+                        },
+                        required: ["postId", "reason"],
+                    },
+                    minItems: 1,
+                    maxItems: 20,
+                },
+                headlineICPCriteria: {
+                    type: "array",
+                    description: "REQUIRED: 3-5 LinkedIn headline criteria for filtering engagers. Each should be a clear yes/no rule.",
+                    items: { type: "string" },
+                    minItems: 3,
+                    maxItems: 5,
+                },
+                selectionMode: {
+                    type: "string",
+                    enum: ["add", "replace"],
+                    description: 'How to apply selections. "add" keeps existing selections; "replace" clears previous selections not included in this call.',
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Headless workflow step ID",
+                },
+            },
+            required: ["campaignOfferId", "selections", "headlineICPCriteria"],
+        },
+    },
+    {
+        name: "set_headline_icp_criteria",
+        description: "Set 3-5 headline ICP criteria for filtering post engagers. Use when user selects posts manually or attempts to scrape without criteria.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                headlineICPCriteria: {
+                    type: "array",
+                    description: "Array of 3-5 yes/no headline criteria for identifying ICP fits.",
+                    items: { type: "string" },
+                    minItems: 3,
+                    maxItems: 5,
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Headless workflow step ID",
+                },
+            },
+            required: ["campaignOfferId", "headlineICPCriteria"],
+        },
+    },
+];
+// Company/organization filter keys that indicate combined search mode
+const COMPANY_FILTER_KEYS = [
+    "organization_num_employees_ranges",
+    "organization_locations",
+    "organization_ids",
+    "organization_not_ids",
+    "q_organization_keyword_tags",
+    "organization_industry_tag_ids",
+    "latest_funding_amount_min",
+    "latest_funding_amount_max",
+    "latest_funding_stage_cd",
+    "organization_revenue_min",
+    "organization_revenue_max",
+];
+function hasCompanyFilters(filters) {
+    return COMPANY_FILTER_KEYS.some((key) => {
+        const value = filters[key];
+        if (value === undefined || value === null)
+            return false;
+        if (Array.isArray(value) && value.length === 0)
+            return false;
+        if (typeof value === "string" && value.trim() === "")
+            return false;
+        return true;
+    });
+}
+function splitFilters(filters) {
+    const companyFilters = {};
+    const contactFilters = {};
+    for (const [key, value] of Object.entries(filters)) {
+        if (COMPANY_FILTER_KEYS.includes(key)) {
+            companyFilters[key] = value;
+        }
+        else if (key === "q_keywords") {
+            // GOTCHA: q_keywords doesn't work in combined search (causes 0 results)
+            // Move it to q_organization_keyword_tags in company filters instead
+            if (value && typeof value === "string" && value.trim()) {
+                // Convert keyword string to tags array if not already using keyword tags
+                if (!companyFilters["q_organization_keyword_tags"]) {
+                    companyFilters["q_organization_keyword_tags"] = value
+                        .split(",")
+                        .map((s) => s.trim())
+                        .filter(Boolean);
+                }
+            }
+            // Don't add q_keywords to contactFilters - it breaks combined search
+        }
+        else {
+            contactFilters[key] = value;
+        }
+    }
+    return { companyFilters, contactFilters };
+}
+// Keys that are NOT filters (workflow/pagination params)
+const NON_FILTER_KEYS = new Set([
+    "searchMode",
+    "filters",
+    "companyFilters",
+    "contactFilters",
+    "page",
+    "searchId",
+    "campaignOfferId",
+    "searchName",
+    "companySearchMode",
+    "uploadedDomains",
+    "currentStep",
+    "confirmed",
+]);
+function resolveCsvHeaderName(headers, requested) {
+    const trimmed = requested.trim();
+    if (!trimmed) {
+        throw new Error("CSV column names must be non-empty strings.");
+    }
+    const exact = headers.find((header) => header === trimmed);
+    if (exact) {
+        return exact;
+    }
+    const lowered = trimmed.toLowerCase();
+    const matches = headers.filter((header) => header.trim().toLowerCase() === lowered);
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    throw new Error(`CSV column "${requested}" does not exist in the current preview. Re-run load_csv_domains preview.`);
+}
+function normalizeConfirmationPayload(payload) {
+    return {
+        ...payload,
+        selectedColumns: [...payload.selectedColumns],
+    };
+}
+function normalizeLinkedinConfirmationPayload(payload) {
+    return {
+        ...payload,
+        selectedColumns: [...payload.selectedColumns],
+    };
+}
+function compareStringArrays(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+function buildCsvPreviewSuggestedToolCalls(input, token) {
+    return [
+        {
+            tool: "load_csv_domains",
+            args: {
+                ...(input.campaignOfferId
+                    ? { campaignOfferId: input.campaignOfferId }
+                    : {}),
+                filePath: input.filePath,
+                confirmed: true,
+                confirmationToken: token,
+            },
+        },
+    ];
+}
+function buildCsvSearchSuggestedToolCalls(campaignOfferId, domainFilterId) {
+    return [
+        {
+            tool: "get_provider_prompt",
+            args: { provider: "prospeo", campaignOfferId },
+        },
+        {
+            tool: "search_prospeo",
+            args: { campaignOfferId, filters: {}, domainFilterId },
+        },
+    ];
+}
+function resolveCsvLinkedinHeaderName(headers, requested) {
+    const trimmed = requested.trim();
+    if (!trimmed) {
+        throw new Error("CSV column names must be non-empty strings.");
+    }
+    const exact = headers.find((header) => header === trimmed);
+    if (exact) {
+        return exact;
+    }
+    const lowered = trimmed.toLowerCase();
+    const matches = headers.filter((header) => header.trim().toLowerCase() === lowered);
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    throw new Error(`CSV column "${requested}" does not exist in the current preview. Re-run load_csv_linkedin_leads preview.`);
+}
+function buildCsvLinkedinPreviewSuggestedToolCalls(input, token) {
+    return [
+        {
+            tool: "load_csv_linkedin_leads",
+            args: {
+                ...(input.campaignOfferId
+                    ? { campaignOfferId: input.campaignOfferId }
+                    : {}),
+                ...(input.currentStep !== undefined
+                    ? { currentStep: input.currentStep }
+                    : {}),
+                ...(input.leadListId ? { leadListId: input.leadListId } : {}),
+                ...(input.leadListName ? { leadListName: input.leadListName } : {}),
+                filePath: input.filePath,
+                confirmed: true,
+                confirmationToken: token,
+            },
+        },
+    ];
+}
+function buildCsvLinkedinConfirmSuggestedToolCalls(campaignOfferId, sourceLeadListId) {
+    return [
+        {
+            tool: "confirm_lead_list",
+            args: { campaignOfferId, sourceLeadListId },
+        },
+    ];
+}
+export async function searchApollo(input) {
+    if (input?.campaignOfferId) {
+        assertInteractionApproval({
+            campaignId: input.campaignOfferId,
+            action: "provider-search",
+            confirmed: input.confirmed,
+        });
+    }
+    assertProviderPromptLoaded({
+        provider: "apollo",
+        campaignOfferId: input?.campaignOfferId,
+    });
+    const api = getApi();
+    const { searchMode: explicitSearchMode, filters: nestedFilters = {}, companyFilters: explicitCompanyFilters, contactFilters: explicitContactFilters, page, searchId, campaignOfferId, searchName, companySearchMode, uploadedDomains, currentStep, ...flatParams } = input || {};
+    // Merge flat parameters with nested filters
+    // Flat params take precedence (they're more explicit)
+    const mergedFilters = {
+        ...nestedFilters,
+    };
+    // Extract flat filters from input
+    for (const [key, value] of Object.entries(flatParams)) {
+        if (!NON_FILTER_KEYS.has(key) && value !== undefined && value !== null) {
+            // Skip empty arrays and empty strings
+            if (Array.isArray(value) && value.length === 0)
+                continue;
+            if (typeof value === "string" && value.trim() === "")
+                continue;
+            mergedFilters[key] = value;
+        }
+    }
+    // Auto-detect combined mode if company filters are present
+    const shouldUseCombined = explicitSearchMode === "combined" ||
+        (explicitSearchMode !== "people" && hasCompanyFilters(mergedFilters));
+    // Build the common request params (non-filter workflow params)
+    const requestParams = {
+        page,
+        searchId,
+        campaignOfferId,
+        searchName,
+        companySearchMode,
+        uploadedDomains,
+        currentStep,
+    };
+    if (shouldUseCombined) {
+        // If explicit company/contact filters provided, use them
+        // Otherwise, split the merged filters object
+        let companyFilters = explicitCompanyFilters;
+        let contactFilters = explicitContactFilters;
+        if (!companyFilters && !contactFilters) {
+            const split = splitFilters(mergedFilters);
+            companyFilters = split.companyFilters;
+            contactFilters = split.contactFilters;
+        }
+        // Combined search: find companies first, then contacts at those companies
+        return api.post(`/api/v2/apollo/combined-search`, {
+            companyFilters: companyFilters || {},
+            contactFilters: contactFilters || {},
+            ...requestParams,
+        });
+    }
+    // Default: direct people search
+    return api.post(`/api/v2/apollo/people-search`, {
+        ...mergedFilters,
+        ...requestParams,
+    });
+}
+export async function searchSalesNav(input) {
+    if (input?.campaignOfferId) {
+        assertInteractionApproval({
+            campaignId: input.campaignOfferId,
+            action: "provider-search",
+            confirmed: input.confirmed,
+        });
+    }
+    assertProviderPromptLoaded({
+        provider: "sales-nav",
+        campaignOfferId: input?.campaignOfferId,
+    });
+    const api = getApi();
+    return api.post(`/api/v3/sales-nav/search`, input);
+}
+export async function searchProspeo(input) {
+    if (input?.campaignOfferId) {
+        assertInteractionApproval({
+            campaignId: input.campaignOfferId,
+            action: "provider-search",
+            confirmed: input.confirmed,
+        });
+    }
+    assertProviderPromptLoaded({
+        provider: "prospeo",
+        campaignOfferId: input?.campaignOfferId,
+    });
+    const api = getApi();
+    const rawInput = input;
+    if ("domains" in rawInput) {
+        throw new Error("search_prospeo does not accept raw domains. Use save_domain_filters and pass domainFilterId.");
+    }
+    const nestedCompany = input?.filters
+        ?.company;
+    if (nestedCompany?.websites !== undefined ||
+        nestedCompany?.names !== undefined) {
+        throw new Error("search_prospeo does not accept filters.company.websites or filters.company.names. Resolve names to domains, then use save_domain_filters and pass domainFilterId.");
+    }
+    const response = await api.post(`/api/v3/prospeo/search`, input);
+    return compactProspeoSearchResponse(response);
+}
+function compactProspeoSearchResponse(response) {
+    if (!response || typeof response !== "object") {
+        return response;
+    }
+    const peopleResults = Array.isArray(response?.people?.results)
+        ? response.people.results
+        : [];
+    const sampleResults = peopleResults.slice(0, 10).map(compactProspeoPerson);
+    return {
+        success: response.success ?? true,
+        searchId: response.searchId ?? null,
+        searchName: response.searchName ?? null,
+        currentPage: response.currentPage ?? null,
+        lastAvailablePage: response.lastAvailablePage ?? null,
+        totalResults: typeof response.totalResults === "number"
+            ? response.totalResults
+            : peopleResults.length,
+        resultsPerPage: typeof response.resultsPerPage === "number"
+            ? response.resultsPerPage
+            : peopleResults.length,
+        nextPageAvailable: typeof response.currentPage === "number" &&
+            typeof response.lastAvailablePage === "number"
+            ? response.currentPage < response.lastAvailablePage
+            : null,
+        people: {
+            count: peopleResults.length,
+            sampleCount: sampleResults.length,
+            results: sampleResults,
+        },
+    };
+}
+function compactProspeoPerson(person) {
+    const currentRole = Array.isArray(person?._prospeo?.job_history)
+        ? (person._prospeo.job_history.find((job) => job?.current) ?? null)
+        : null;
+    const location = [person?.city, person?.country]
+        .filter((value) => typeof value === "string" && value.trim())
+        .join(", ");
+    return {
+        name: person?.name ?? null,
+        title: person?.title ?? currentRole?.title ?? null,
+        company: person?.organization?.name ?? currentRole?.company_name ?? null,
+        linkedinUrl: person?.linkedin_url ?? null,
+        email: person?.email ?? null,
+        emailStatus: person?.emailStatus ?? null,
+        location: location || null,
+        headline: person?._prospeo?.headline ?? null,
+        currentRole: currentRole
+            ? {
+                title: currentRole.title ?? null,
+                company: currentRole.company_name ?? null,
+                seniority: currentRole.seniority ?? null,
+                departments: Array.isArray(currentRole.departments)
+                    ? currentRole.departments
+                    : [],
+                startYear: currentRole.start_year ?? null,
+                startMonth: currentRole.start_month ?? null,
+            }
+            : null,
+    };
+}
+export async function loadCsvDomains(input) {
+    const api = getApi();
+    if (!input?.filePath) {
+        throw new Error("load_csv_domains requires filePath.");
+    }
+    if (input.confirmed) {
+        if (!input.confirmationToken) {
+            throw new Error("load_csv_domains confirmed execution requires confirmationToken from a preview response.");
+        }
+        const tokenPayload = normalizeConfirmationPayload(parseConfirmationToken(input.confirmationToken));
+        const previewBuild = buildCsvDomainPreview({
+            filePath: input.filePath,
+            domainColumn: tokenPayload.domainColumn,
+            selectedColumns: tokenPayload.selectedColumns,
+            workspaceRoot,
+        });
+        const currentPayload = {
+            version: tokenPayload.version,
+            filePath: previewBuild.preview.resolvedFilePath,
+            fileSizeBytes: previewBuild.fileSizeBytes,
+            fileMtimeMs: previewBuild.fileMtimeMs,
+            domainColumn: previewBuild.resolvedDomainColumn ?? "",
+            selectedColumns: previewBuild.preview.selectedColumns,
+        };
+        if (!matchesConfirmationToken(input.confirmationToken, currentPayload)) {
+            throw new Error("CSV file changed after preview. Re-run load_csv_domains preview before confirming.");
+        }
+        if (input.domainColumn) {
+            const requestedDomainColumn = resolveCsvHeaderName(previewBuild.preview.headers, input.domainColumn);
+            if (requestedDomainColumn !== tokenPayload.domainColumn) {
+                throw new Error("domainColumn changed after preview. Re-run load_csv_domains preview before confirming.");
+            }
+        }
+        if (input.selectedColumns) {
+            const requestedSelectedColumns = input.selectedColumns.map((column) => resolveCsvHeaderName(previewBuild.preview.headers, column));
+            if (!compareStringArrays(requestedSelectedColumns, tokenPayload.selectedColumns)) {
+                throw new Error("selectedColumns changed after preview. Re-run load_csv_domains preview before confirming.");
+            }
+        }
+        if (previewBuild.preview.blockingErrors.length > 0) {
+            throw new Error(`CSV preview is no longer actionable: ${previewBuild.preview.blockingErrors.join(" ")}`);
+        }
+        if (!previewBuild.resolvedDomainColumn) {
+            throw new Error("CSV preview no longer has a resolved domain column. Re-run load_csv_domains preview.");
+        }
+        const carryRows = projectCsvCarryRows(previewBuild);
+        const response = await api.post("/api/v3/prospeo/validate-domains", {
+            domains: previewBuild.keptCandidateDomains,
+            target: "include",
+            carry: {
+                domainColumn: previewBuild.resolvedDomainColumn,
+                selectedColumns: previewBuild.preview.selectedColumns,
+                rows: carryRows,
+            },
+        });
+        const validCount = Array.isArray(response.valid)
+            ? response.valid.length
+            : 0;
+        const invalidCount = Array.isArray(response.invalid)
+            ? response.invalid.length
+            : 0;
+        const droppedCount = Array.isArray(response.dropped)
+            ? response.dropped.length
+            : 0;
+        if (!response.domainFilterId ||
+            typeof response.domainFilterId !== "string") {
+            throw new Error("Prospeo validation did not return a domainFilterId for the confirmed CSV upload.");
+        }
+        if (validCount === 0) {
+            throw new Error(`CSV upload produced zero valid domains after backend validation (invalid=${invalidCount}, dropped=${droppedCount}).`);
+        }
+        return {
+            ok: true,
+            requiresConfirmation: false,
+            resolvedFilePath: previewBuild.preview.resolvedFilePath,
+            domainColumn: previewBuild.resolvedDomainColumn,
+            selectedColumns: previewBuild.preview.selectedColumns,
+            domainFilterId: response.domainFilterId,
+            validCount,
+            invalidCount,
+            droppedCount,
+            truncatedDomainCount: previewBuild.preview.truncatedDomainCount,
+            apiCallCount: typeof response.apiCallCount === "number" ? response.apiCallCount : 0,
+            duplicatePolicy: previewBuild.preview.duplicatePolicy,
+            limits: previewBuild.preview.limits,
+            warnings: previewBuild.preview.warnings,
+            suggestedToolCalls: input.campaignOfferId
+                ? buildCsvSearchSuggestedToolCalls(input.campaignOfferId, response.domainFilterId)
+                : [],
+            guidance: input.campaignOfferId
+                ? "Domain filter is ready. Load the Prospeo provider prompt, then run search_prospeo with the returned domainFilterId."
+                : "Domain filter is ready. Pass the returned domainFilterId into search_prospeo once you have a campaignOfferId.",
+        };
+    }
+    const previewBuild = buildCsvDomainPreview({
+        filePath: input.filePath,
+        domainColumn: input.domainColumn,
+        selectedColumns: input.selectedColumns,
+        workspaceRoot,
+    });
+    const preview = previewBuild.preview;
+    if (preview.blockingErrors.length > 0) {
+        return {
+            ok: false,
+            requiresConfirmation: false,
+            preview,
+            suggestedToolCalls: [],
+        };
+    }
+    if (!preview.confirmationToken || !previewBuild.resolvedDomainColumn) {
+        return {
+            ok: false,
+            requiresConfirmation: false,
+            preview,
+            suggestedToolCalls: [],
+        };
+    }
+    return {
+        ok: true,
+        requiresConfirmation: true,
+        preview,
+        confirmationToken: preview.confirmationToken,
+        suggestedToolCalls: buildCsvPreviewSuggestedToolCalls(input, preview.confirmationToken),
+    };
+}
+export async function loadCsvLinkedinLeads(input) {
+    const api = getApi();
+    if (!input?.filePath) {
+        throw new Error("load_csv_linkedin_leads requires filePath.");
+    }
+    if (input.confirmed) {
+        if (!input.confirmationToken) {
+            throw new Error("load_csv_linkedin_leads confirmed execution requires confirmationToken from a preview response.");
+        }
+        const tokenPayload = normalizeLinkedinConfirmationPayload(parseLinkedinConfirmationToken(input.confirmationToken));
+        const previewBuild = buildCsvLinkedinPreview({
+            filePath: input.filePath,
+            linkedInColumn: tokenPayload.linkedInColumn,
+            selectedColumns: tokenPayload.selectedColumns,
+            workspaceRoot,
+        });
+        const currentPayload = {
+            version: tokenPayload.version,
+            filePath: previewBuild.preview.resolvedFilePath,
+            fileSizeBytes: previewBuild.fileSizeBytes,
+            fileMtimeMs: previewBuild.fileMtimeMs,
+            linkedInColumn: previewBuild.resolvedLinkedInColumn ?? "",
+            selectedColumns: previewBuild.preview.selectedColumns,
+        };
+        if (!matchesLinkedinConfirmationToken(input.confirmationToken, currentPayload)) {
+            throw new Error("CSV file changed after preview. Re-run load_csv_linkedin_leads preview before confirming.");
+        }
+        if (input.linkedInColumn) {
+            const requestedLinkedInColumn = resolveCsvLinkedinHeaderName(previewBuild.preview.headers, input.linkedInColumn);
+            if (requestedLinkedInColumn !== tokenPayload.linkedInColumn) {
+                throw new Error("linkedInColumn changed after preview. Re-run load_csv_linkedin_leads preview before confirming.");
+            }
+        }
+        if (input.selectedColumns) {
+            const requestedSelectedColumns = input.selectedColumns.map((column) => resolveCsvLinkedinHeaderName(previewBuild.preview.headers, column));
+            if (!compareStringArrays(requestedSelectedColumns, tokenPayload.selectedColumns)) {
+                throw new Error("selectedColumns changed after preview. Re-run load_csv_linkedin_leads preview before confirming.");
+            }
+        }
+        if (previewBuild.preview.blockingErrors.length > 0) {
+            throw new Error(`CSV preview is no longer actionable: ${previewBuild.preview.blockingErrors.join(" ")}`);
+        }
+        if (!previewBuild.resolvedLinkedInColumn) {
+            throw new Error("CSV preview no longer has a resolved LinkedIn URL column. Re-run load_csv_linkedin_leads preview.");
+        }
+        const leadListName = input.leadListName?.trim() || previewBuild.preview.suggestedLeadListName;
+        let leadListId = input.leadListId?.trim() || "";
+        let createdLeadList = false;
+        let existingRowCount = 0;
+        if (leadListId) {
+            const tableMeta = await api.get(`/api/v3/workflow-tables/${leadListId}?mode=meta`);
+            const tableType = tableMeta.table?.config
+                ?.type;
+            if (tableType !== "lead_list") {
+                throw new Error(`Existing table ${leadListId} is not a lead list and cannot accept LinkedIn CSV uploads.`);
+            }
+            existingRowCount = tableMeta.rowCount ?? 0;
+        }
+        else {
+            const created = await api.post("/api/v3/lead-lists", {
+                name: leadListName,
+            });
+            leadListId = created.leadList?.id ?? "";
+            if (!leadListId) {
+                throw new Error("Lead list creation did not return a leadList.id for the CSV upload.");
+            }
+            createdLeadList = true;
+        }
+        const uploadedFile = await uploadCsvLinkedinFile({
+            api,
+            leadListId,
+            filePath: input.filePath,
+            workspaceRoot,
+            fileSizeBytes: previewBuild.fileSizeBytes,
+        });
+        const importMode = existingRowCount > 0 ? "add" : undefined;
+        const importStart = await api.post(`/api/v3/lead-lists/${leadListId}/csv-import/start`, {
+            bucket: uploadedFile.bucket,
+            objectPath: uploadedFile.objectPath,
+            originalFilename: uploadedFile.originalFilename,
+            contentType: uploadedFile.contentType,
+            fileSizeBytes: uploadedFile.fileSizeBytes,
+            linkedInColumn: previewBuild.resolvedLinkedInColumn,
+            selectedColumns: previewBuild.preview.selectedColumns,
+            standardMappings: previewBuild.preview.standardMappings,
+            customColumnTargets: previewBuild.preview.customColumnTargets,
+            targetLeadCount: previewBuild.preview.validLinkedInRowCount,
+            duplicateCount: previewBuild.preview.duplicateLinkedInCount,
+            invalidCount: previewBuild.preview.invalidLinkedInRowCount,
+            ...(importMode ? { mode: importMode } : {}),
+        });
+        if (input.campaignOfferId) {
+            await api.put(`/api/v2/campaign-offers/${input.campaignOfferId}`, {
+                selectedLeadListId: leadListId,
+                ...(input.currentStep !== undefined
+                    ? { currentStep: input.currentStep }
+                    : {}),
+            });
+        }
+        const readiness = await waitForLeadListReady({
+            leadListId,
+            provider: "csv-linkedin",
+            jobId: importStart.jobId,
+            targetLeadCount: importStart.effectiveTargetLeadCount ??
+                importStart.targetLeadCount ??
+                previewBuild.preview.validLinkedInRowCount,
+            timeoutMs: 5000,
+            intervalMs: 1000,
+        });
+        if (!readiness.ready) {
+            if (readiness.reason === "import_failed") {
+                throw new Error(readiness.error || "CSV import failed. Please retry the upload.");
+            }
+            throw new Error("CSV import is still processing. Re-run the tool shortly.");
+        }
+        return {
+            ok: true,
+            requiresConfirmation: false,
+            resolvedFilePath: previewBuild.preview.resolvedFilePath,
+            linkedInColumn: previewBuild.resolvedLinkedInColumn,
+            selectedColumns: previewBuild.preview.selectedColumns,
+            standardMappings: previewBuild.preview.standardMappings,
+            customColumnTargets: previewBuild.preview.customColumnTargets,
+            leadListId,
+            leadListName,
+            createdLeadList,
+            selectedLeadListIdUpdated: Boolean(input.campaignOfferId),
+            rowsInserted: typeof readiness.rowCount === "number"
+                ? readiness.rowCount
+                : previewBuild.preparedRows.length,
+            jobId: importStart.jobId ?? null,
+            importStatus: readiness.status ?? importStart.status ?? null,
+            validCount: previewBuild.preview.validLinkedInRowCount,
+            invalidCount: previewBuild.preview.invalidLinkedInRowCount,
+            duplicateCount: previewBuild.preview.duplicateLinkedInCount,
+            emptyLinkedInRowCount: previewBuild.preview.emptyLinkedInRowCount,
+            duplicatePolicy: previewBuild.preview.duplicatePolicy,
+            limits: previewBuild.preview.limits,
+            warnings: previewBuild.preview.warnings,
+            readinessWarning: readiness.warning ?? null,
+            suggestedToolCalls: input.campaignOfferId
+                ? buildCsvLinkedinConfirmSuggestedToolCalls(input.campaignOfferId, leadListId)
+                : [],
+            guidance: input.campaignOfferId
+                ? "Lead list is ready. Review it, then call confirm_lead_list when the user approves importing it into the campaign table."
+                : "Lead list is ready. Reuse the returned leadListId when attaching this audience to a campaign later.",
+        };
+    }
+    const previewBuild = buildCsvLinkedinPreview({
+        filePath: input.filePath,
+        linkedInColumn: input.linkedInColumn,
+        selectedColumns: input.selectedColumns,
+        workspaceRoot,
+    });
+    const preview = previewBuild.preview;
+    if (preview.blockingErrors.length > 0) {
+        return {
+            ok: false,
+            requiresConfirmation: false,
+            preview,
+            suggestedToolCalls: [],
+        };
+    }
+    if (!preview.confirmationToken || !previewBuild.resolvedLinkedInColumn) {
+        return {
+            ok: false,
+            requiresConfirmation: false,
+            preview,
+            suggestedToolCalls: [],
+        };
+    }
+    return {
+        ok: true,
+        requiresConfirmation: true,
+        preview,
+        confirmationToken: preview.confirmationToken,
+        suggestedToolCalls: buildCsvLinkedinPreviewSuggestedToolCalls(input, preview.confirmationToken),
+    };
+}
+export async function saveDomainFilters(input) {
+    const api = getApi();
+    return api.post(`/api/v3/prospeo/domain-filters`, {
+        include: input.include,
+        exclude: input.exclude,
+    });
+}
+export async function lookupSalesNavFilter(input) {
+    const api = getApi();
+    const { filterType, query } = input;
+    const response = await api.post(`/api/v3/sales-nav/autocomplete`, { filterType, query });
+    if (!response.success) {
+        throw new Error(response.message || "Failed to lookup filter options");
+    }
+    return {
+        filterType,
+        query,
+        options: response.options.map((opt) => ({
+            id: opt.id,
+            displayValue: opt.displayValue || opt.text,
+            text: opt.text || opt.displayValue,
+        })),
+        usage: `Use these in search_sales_nav filters like: { "type": "${filterType}", "values": [{ "id": "${response.options[0]?.id || "ID"}", "text": "${response.options[0]?.text || "TEXT"}", "selectionType": "INCLUDED" }] }`,
+    };
+}
+export async function searchSignals(input) {
+    if (input?.campaignOfferId) {
+        assertInteractionApproval({
+            campaignId: input.campaignOfferId,
+            action: "provider-search",
+            confirmed: input.confirmed,
+        });
+    }
+    assertProviderPromptLoaded({
+        provider: "signal-discovery",
+        campaignOfferId: input?.campaignOfferId,
+    });
+    const api = getApi();
+    const { campaignOfferId, headlineICPCriteria, rubricGuidelines } = input;
+    const effectiveHeadlineICPCriteria = headlineICPCriteria && headlineICPCriteria.length > 0
+        ? headlineICPCriteria
+        : rubricGuidelines;
+    // Persist criteria early so user take-over has filters ready.
+    if (campaignOfferId && effectiveHeadlineICPCriteria?.length) {
+        await api.patch(`/api/v3/campaigns/${campaignOfferId}/signal-discovery/posts`, {
+            selectedIds: [],
+            unselectedIds: [],
+            headlineICPCriteria: effectiveHeadlineICPCriteria,
+            rubricGuidelines: effectiveHeadlineICPCriteria,
+        });
+    }
+    const response = await api.post(`/api/v1/signal-discovery/search-signals`, input);
+    return summarizeSignalSearchResponse(response);
+}
+export async function importLeads(input) {
+    const api = getApi();
+    const { campaignOfferId, currentStep, sourceLeadListId: inputSourceLeadListId, searchId, targetLeadCount, mode, searchName, leadListName, headlineICPCriteria, rubricGuidelines, confirmed, } = input;
+    assertInteractionApproval({
+        campaignId: campaignOfferId,
+        action: "import-leads",
+        confirmed,
+    });
+    // Make sourceLeadListId mutable so it can be auto-resolved from campaign
+    let sourceLeadListId = inputSourceLeadListId;
+    // Auto-detect provider from campaign if not specified
+    let provider = input.provider;
+    let campaignCurrentStep;
+    let campaignSelectedLeadListId;
+    if (!provider || currentStep === undefined || mode === undefined) {
+        // Pull campaign once when we need provider or to determine default step behavior.
+        const campaign = await api.get(`/api/v2/campaign-offers/${campaignOfferId}`);
+        if (!provider) {
+            const leadSourceProvider = campaign.leadSourceProvider;
+            provider =
+                leadSourceProvider === "apollo-ai" || leadSourceProvider === "apollo"
+                    ? "apollo"
+                    : leadSourceProvider === "sales-nav"
+                        ? "sales-nav"
+                        : leadSourceProvider === "prospeo"
+                            ? "prospeo"
+                            : leadSourceProvider === "signal-discovery"
+                                ? "signal-discovery"
+                                : undefined;
+        }
+        if (currentStep === undefined) {
+            campaignCurrentStep = campaign.currentStep ?? null;
+        }
+        campaignSelectedLeadListId = campaign.selectedLeadListId ?? null;
+    }
+    // If caller doesn't specify a step, default to showing the lead list
+    // while in lead sourcing phases. Pass null to skip auto-advance.
+    const sourcingSteps = new Set([
+        null,
+        "pick-provider",
+        "apollo",
+        "sales-nav",
+        "prospeo",
+        "signal-discovery",
+        "signal-discovery-results",
+    ]);
+    const shouldDefaultStep = currentStep === undefined && sourcingSteps.has(campaignCurrentStep ?? null);
+    const effectiveCurrentStep = shouldDefaultStep
+        ? "confirm-lead-list"
+        : currentStep;
+    const shouldSetCurrentStep = typeof effectiveCurrentStep === "string" && effectiveCurrentStep.length > 0;
+    const normalizedMode = mode === "add" || mode === "replace" ? mode : undefined;
+    // If no sourceLeadListId but campaign has one selected, handle mode selection
+    if (!sourceLeadListId && campaignSelectedLeadListId) {
+        // If mode is provided but sourceLeadListId is missing, remind LLM to pass it
+        if (normalizedMode) {
+            return {
+                error: "sourceLeadListId_required",
+                message: `Mode "${normalizedMode}" requires sourceLeadListId. Pass the existingLeadListId from the previous needsModeSelection response.`,
+                existingLeadListId: campaignSelectedLeadListId,
+                suggestedToolCalls: [
+                    {
+                        tool: "import_leads",
+                        args: {
+                            ...input,
+                            sourceLeadListId: campaignSelectedLeadListId,
+                        },
+                    },
+                ],
+            };
+        }
+        // No mode provided - ask user to choose
+        return {
+            provider: provider || "apollo",
+            leadListId: campaignSelectedLeadListId,
+            existingLeadListId: campaignSelectedLeadListId,
+            needsModeSelection: true,
+            modeOptions: ["add", "replace"],
+            message: "A lead list already exists for this campaign. Should I add to it or replace it?",
+            suggestedToolCalls: [
+                {
+                    tool: "import_leads",
+                    args: {
+                        ...input,
+                        sourceLeadListId: campaignSelectedLeadListId,
+                        mode: "add",
+                    },
+                },
+                {
+                    tool: "import_leads",
+                    args: {
+                        ...input,
+                        sourceLeadListId: campaignSelectedLeadListId,
+                        mode: "replace",
+                    },
+                },
+            ],
+        };
+    }
+    const normalizedProvider = provider === "sales-nav" || provider === "prospeo" ? provider : "apollo";
+    const providerForGuard = provider === "sales-nav" ||
+        provider === "prospeo" ||
+        provider === "signal-discovery"
+        ? provider
+        : "apollo";
+    assertProviderPromptLoaded({
+        provider: providerForGuard,
+        campaignOfferId,
+    });
+    const maxImportCount = getMaxImportCount(normalizedProvider);
+    const normalizedTargetLeadCount = normalizeTargetLeadCount(targetLeadCount, maxImportCount);
+    const requestedLeadCount = normalizedTargetLeadCount ??
+        (normalizedProvider === "sales-nav" || normalizedProvider === "prospeo"
+            ? 100
+            : undefined);
+    const cappedTargetLeadCount = requestedLeadCount !== undefined
+        ? Math.min(requestedLeadCount, maxImportCount)
+        : undefined;
+    // === SIGNAL DISCOVERY FLOW ===
+    if (provider === "signal-discovery") {
+        // Get selected posts from the campaign's signal search tabs
+        // Note: API returns flat fields (postUrl, postContent, authorName, etc.)
+        const tabsResponse = await api.get(`/api/v3/campaigns/${campaignOfferId}/signal-discovery/tabs`);
+        // Collect all selected posts, mapping from API format to signal-leads/create format
+        const selectedPosts = [];
+        for (const tab of tabsResponse.tabs || []) {
+            for (const post of tab.posts || []) {
+                if (post.isSelected) {
+                    selectedPosts.push({
+                        id: post.id,
+                        url: post.postUrl,
+                        content: post.postContent,
+                        likes: post.likes,
+                        comments: post.comments,
+                        keyword: tab.keyword,
+                        postedAt: post.postedAt,
+                        author: {
+                            name: post.authorName,
+                            headline: post.authorHeadline || "",
+                        },
+                    });
+                }
+            }
+        }
+        if (selectedPosts.length === 0) {
+            throw new Error("No posts selected. Call select_promising_posts first.");
+        }
+        // De-duplicate selected posts by canonical URL to avoid double scraping.
+        const uniqueByUrl = new Map();
+        for (const post of selectedPosts) {
+            const key = normalizePostUrl(post.url) || post.url;
+            const existing = uniqueByUrl.get(key);
+            if (!existing) {
+                uniqueByUrl.set(key, post);
+                continue;
+            }
+            const existingEngagement = existing.likes + existing.comments;
+            const postEngagement = post.likes + post.comments;
+            if (postEngagement > existingEngagement) {
+                uniqueByUrl.set(key, post);
+            }
+        }
+        const uniqueSelectedPosts = Array.from(uniqueByUrl.values());
+        const effectiveHeadlineICPCriteria = headlineICPCriteria && headlineICPCriteria.length > 0
+            ? headlineICPCriteria
+            : rubricGuidelines;
+        // Start the scrape job
+        const result = await api.post(`/api/v3/campaigns/${campaignOfferId}/signal-leads/create`, {
+            posts: uniqueSelectedPosts,
+            ...(effectiveHeadlineICPCriteria &&
+                effectiveHeadlineICPCriteria.length > 0
+                ? {
+                    headlineICPCriteria: effectiveHeadlineICPCriteria,
+                    rubricGuidelines: effectiveHeadlineICPCriteria,
+                }
+                : {}),
+        });
+        // CRITICAL: Update selectedLeadListId so UI subscribes to correct table
+        // This enables realtime updates in LeadListCanvas
+        await api.put(`/api/v2/campaign-offers/${campaignOfferId}`, {
+            selectedLeadListId: result.tableId,
+            ...(shouldSetCurrentStep ? { currentStep: effectiveCurrentStep } : {}),
+        });
+        return {
+            provider: "signal-discovery",
+            leadListId: result.tableId,
+            jobId: result.jobId,
+            estimatedEngagers: result.estimatedEngagers,
+            selectedPostCount: uniqueSelectedPosts.length,
+            targetLeadCount: cappedTargetLeadCount ?? null,
+            message: `Started scraping ${uniqueSelectedPosts.length} posts (~${result.estimatedEngagers} engagers). Leads will appear as scraping completes.`,
+        };
+    }
+    // === APOLLO / SALES NAV FLOW ===
+    let leadListId = sourceLeadListId;
+    let createdLeadList = null;
+    // Create lead list if not provided
+    if (!leadListId) {
+        if (!searchId) {
+            throw new Error(`import_leads for ${provider || "apollo"} requires sourceLeadListId or searchId`);
+        }
+        const providerLabel = provider === "sales-nav"
+            ? "Sales Nav"
+            : provider === "prospeo"
+                ? "Prospeo"
+                : "Apollo";
+        const fallbackName = leadListName ||
+            (searchName ? `${providerLabel} - ${searchName}` : undefined) ||
+            `${providerLabel} Import ${new Date().toISOString().slice(0, 10)}`;
+        const createResult = await api.post(`/api/v3/lead-lists`, {
+            name: fallbackName,
+            templateType: "lead_list",
+        });
+        leadListId = createResult.leadList?.id;
+        createdLeadList = createResult.leadList;
+    }
+    if (!leadListId) {
+        throw new Error("Failed to determine lead list ID for import");
+    }
+    // Start import job based on provider
+    let jobResult = null;
+    let jobId;
+    if (searchId) {
+        const startImport = async () => {
+            if (provider === "sales-nav") {
+                // Sales Nav export flow
+                return api.post(`/api/v3/sales-nav/export`, {
+                    searchId,
+                    workflowTableId: leadListId,
+                    targetLeadCount: cappedTargetLeadCount ?? 100,
+                    ...(normalizedMode ? { mode: normalizedMode } : {}),
+                });
+            }
+            if (provider === "prospeo") {
+                return api.post(`/api/v3/lead-lists/${leadListId}/prospeo-import/start`, {
+                    searchId,
+                    targetLeadCount: cappedTargetLeadCount,
+                    ...(normalizedMode ? { mode: normalizedMode } : {}),
+                });
+            }
+            // Apollo import flow (default)
+            return api.post(`/api/v3/lead-lists/${leadListId}/apollo-import/start`, {
+                searchId,
+                targetLeadCount: cappedTargetLeadCount,
+                ...(normalizedMode ? { mode: normalizedMode } : {}),
+            });
+        };
+        try {
+            jobResult = await startImport();
+            jobId = jobResult?.jobId;
+        }
+        catch (error) {
+            if (error instanceof SellableApiError && error.status === 429) {
+                const parsed = parseApiErrorBody(error.body) || {};
+                if (parsed.error === "lead_list_exists" || parsed.modeRequired) {
+                    return {
+                        provider: provider || "apollo",
+                        leadListId,
+                        existingLeadListId: leadListId,
+                        needsModeSelection: true,
+                        modeOptions: ["add", "replace"],
+                        existingCount: typeof parsed.existingCount === "number"
+                            ? parsed.existingCount
+                            : undefined,
+                        message: "This lead list already has rows. Should I add to it or replace it?",
+                        suggestedToolCalls: [
+                            {
+                                tool: "import_leads",
+                                args: {
+                                    ...input,
+                                    sourceLeadListId: leadListId,
+                                    mode: "add",
+                                },
+                            },
+                            {
+                                tool: "import_leads",
+                                args: {
+                                    ...input,
+                                    sourceLeadListId: leadListId,
+                                    mode: "replace",
+                                },
+                            },
+                        ],
+                    };
+                }
+            }
+            throw error;
+        }
+    }
+    // Update selectedLeadListId so UI subscribes to the source lead list
+    // This enables realtime updates while the import job runs.
+    await api.put(`/api/v2/campaign-offers/${campaignOfferId}`, {
+        selectedLeadListId: leadListId,
+        ...(shouldSetCurrentStep ? { currentStep: effectiveCurrentStep } : {}),
+    });
+    return {
+        provider: provider || "apollo",
+        leadListId,
+        createdLeadList,
+        jobResult,
+        jobId,
+        targetLeadCount: cappedTargetLeadCount ?? null,
+        message: "Import started. Review the lead list as it fills; once it looks good, confirm to import into the campaign table.",
+    };
+}
+export async function cancelLeadImport(input) {
+    if (!input.campaignOfferId) {
+        throw new Error("cancel_lead_import: campaignOfferId is required.");
+    }
+    if (!input.tableId) {
+        throw new Error("cancel_lead_import: tableId is required.");
+    }
+    if (input.provider !== "apollo" &&
+        input.provider !== "prospeo" &&
+        input.provider !== "sales-nav") {
+        throw new Error(`cancel_lead_import: provider must be 'apollo', 'prospeo', or 'sales-nav' (got '${input.provider}'). Signal Discovery is not supported.`);
+    }
+    const api = getApi();
+    const path = input.provider === "apollo"
+        ? `/api/v3/lead-lists/${input.tableId}/apollo-import/cancel`
+        : input.provider === "sales-nav"
+            ? `/api/v3/lead-lists/${input.tableId}/sales-nav-import/cancel`
+            : `/api/v3/lead-lists/${input.tableId}/prospeo-import/cancel`;
+    try {
+        const result = await api.post(path, {});
+        return {
+            cancelled: true,
+            provider: input.provider,
+            tableId: input.tableId,
+            jobId: result.jobId,
+            status: result.status,
+            fetchedLeads: result.fetchedLeads,
+            previousStatus: result.previousStatus,
+        };
+    }
+    catch (error) {
+        if (error?.status === 404 || /404/.test(error?.message ?? "")) {
+            return {
+                cancelled: false,
+                provider: input.provider,
+                tableId: input.tableId,
+                reason: "no_active_import",
+            };
+        }
+        throw error;
+    }
+}
+export async function confirmLeadList(input) {
+    const api = getApi();
+    const { campaignOfferId, currentStep, confirmed, sourceLeadListId, campaignName, keepInSync, jobId, targetLeadCount, } = input;
+    assertInteractionApproval({
+        campaignId: campaignOfferId,
+        action: "confirm-lead-list",
+        confirmed,
+    });
+    let resolvedLeadListId = sourceLeadListId;
+    let resolvedProvider;
+    if (!resolvedLeadListId || currentStep === undefined || !resolvedProvider) {
+        const campaign = await api.get(`/api/v2/campaign-offers/${campaignOfferId}`);
+        if (!resolvedLeadListId) {
+            resolvedLeadListId = campaign.selectedLeadListId ?? undefined;
+        }
+        if (!resolvedProvider) {
+            const leadSourceProvider = campaign.leadSourceProvider;
+            resolvedProvider =
+                leadSourceProvider === "apollo-ai" || leadSourceProvider === "apollo"
+                    ? "apollo"
+                    : leadSourceProvider === "sales-nav"
+                        ? "sales-nav"
+                        : leadSourceProvider === "prospeo"
+                            ? "prospeo"
+                            : leadSourceProvider === "signal-discovery"
+                                ? "signal-discovery"
+                                : undefined;
+        }
+        // currentStep defaults handled below
+    }
+    if (!resolvedLeadListId) {
+        throw new Error("confirm_lead_list requires sourceLeadListId");
+    }
+    const effectiveCurrentStep = currentStep === undefined ? "confirm-lead-list" : currentStep;
+    const shouldSetCurrentStep = typeof effectiveCurrentStep === "string" && effectiveCurrentStep.length > 0;
+    let readiness;
+    const leadListMeta = await api.get(`/api/v3/workflow-tables/${resolvedLeadListId}?mode=meta`);
+    const leadListConfig = leadListMeta.table?.config ?? null;
+    const leadListRowCount = leadListMeta.rowCount ?? 0;
+    const importProgress = leadListConfig?.importProgress ?? null;
+    const progressProcessed = typeof importProgress?.processed === "number"
+        ? importProgress.processed
+        : null;
+    const progressTotal = typeof importProgress?.total === "number" ? importProgress.total : null;
+    const progressImported = typeof importProgress?.leadsImported === "number"
+        ? importProgress.leadsImported
+        : null;
+    const csvImportRowsMaterialized = leadListConfig?.importProvider === "csv-linkedin" &&
+        leadListRowCount > 0 &&
+        progressImported !== null &&
+        progressImported >= leadListRowCount &&
+        (progressProcessed === null ||
+            progressTotal === null ||
+            progressProcessed >= progressTotal);
+    const hasProviderImportMetadata = Boolean(leadListConfig?.importProvider || leadListConfig?.importJobId);
+    const hasAsyncImportMetadata = Boolean(leadListConfig?.importStatus || hasProviderImportMetadata);
+    if ((!hasAsyncImportMetadata ||
+        !hasProviderImportMetadata ||
+        csvImportRowsMaterialized) &&
+        leadListRowCount > 0) {
+        readiness = {
+            ready: true,
+            leadListId: resolvedLeadListId,
+            provider: null,
+            attempts: 1,
+            elapsedMs: 0,
+            rowCount: leadListRowCount,
+            status: null,
+            targetLeadCount: leadListRowCount,
+        };
+    }
+    else {
+        readiness = await waitForLeadListReady({
+            leadListId: resolvedLeadListId,
+            campaignOfferId,
+            provider: resolvedProvider,
+            jobId,
+            targetLeadCount,
+            timeoutMs: 5000,
+            intervalMs: 1000,
+        });
+    }
+    if (!readiness.ready) {
+        if (readiness.reason === "missing_job_id") {
+            throw new Error("Import job ID is missing. Please provide the jobId for this import.");
+        }
+        if (readiness.reason === "import_failed") {
+            throw new Error("Import failed. Please retry before confirming.");
+        }
+        throw new Error("Import still in progress. Please wait for completion.");
+    }
+    const importResult = await api.post(`/api/v3/campaign-builder/import-leads`, {
+        sourceLeadListId: resolvedLeadListId,
+        campaignOfferId,
+        campaignName,
+        keepInSync,
+        ...(shouldSetCurrentStep ? { currentStep: effectiveCurrentStep } : {}),
+    });
+    const campaignTableId = importResult.workflowTableId ?? importResult.campaignTableId;
+    if (campaignTableId) {
+        await api.put(`/api/v2/campaign-offers/${campaignOfferId}`, {
+            selectedLeadListId: campaignTableId,
+            ...(shouldSetCurrentStep ? { currentStep: effectiveCurrentStep } : {}),
+        });
+    }
+    return {
+        sourceLeadListId: resolvedLeadListId,
+        campaignTableId: campaignTableId ?? null,
+        importResult,
+        message: "Lead list imported into campaign table. Next: move to filter-choice, then wait_for_campaign_table_ready, then sample with get_rows_minimal.",
+    };
+}
+export function getProviderPrompt(input) {
+    const { provider, campaignOfferId, confirmed } = input;
+    if (campaignOfferId) {
+        assertInteractionApproval({
+            campaignId: campaignOfferId,
+            action: "provider-preflight",
+            confirmed,
+        });
+    }
+    const providerFiles = {
+        apollo: "apollo.md",
+        "sales-nav": "sales-nav.md",
+        prospeo: "prospeo.md",
+        "signal-discovery": "signal-discovery.md",
+    };
+    const filename = providerFiles[provider];
+    if (!filename) {
+        throw new Error(`Unknown provider: ${provider}. Valid options: apollo, sales-nav, prospeo, signal-discovery`);
+    }
+    const promptPath = join(workspaceRoot, "mcp/sellable/skills/providers", filename);
+    try {
+        const prompt = readFileSync(promptPath, "utf-8");
+        markProviderPromptLoaded({
+            provider,
+            campaignOfferId,
+        });
+        return prompt;
+    }
+    catch (error) {
+        throw new Error(`Failed to read provider prompt for ${provider}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function selectPromisingPosts(input) {
+    const api = getApi();
+    const { campaignOfferId, selections, headlineICPCriteria, currentStep, selectionMode, mode, } = input;
+    const effectiveMode = selectionMode ?? mode ?? "add";
+    // Update post selections via API
+    const postIds = selections.map((s) => s.postId);
+    let unselectedIds = [];
+    if (effectiveMode === "replace") {
+        const existing = await api.get(`/api/v3/campaigns/${campaignOfferId}/signal-discovery/posts?selected=true`);
+        const existingIds = existing?.posts
+            ?.map((post) => post.id)
+            .filter((id) => Boolean(id)) ?? [];
+        const selectedSet = new Set(postIds);
+        unselectedIds = existingIds.filter((id) => !selectedSet.has(id));
+    }
+    const selectionResult = await api.patch(`/api/v3/campaigns/${campaignOfferId}/signal-discovery/posts`, {
+        selectedIds: postIds,
+        unselectedIds,
+        headlineICPCriteria,
+        rubricGuidelines: headlineICPCriteria,
+    });
+    // Update currentStep if provided (via v2 endpoint)
+    if (currentStep) {
+        await api.put(`/api/v2/campaign-offers/${campaignOfferId}`, {
+            currentStep,
+        });
+    }
+    return {
+        success: true,
+        selectedCount: selectionResult.selectedCount,
+        unselectedCount: selectionResult.unselectedCount,
+        criteriaCount: selectionResult.criteriaCount,
+        message: `Selected ${selectionResult.selectedCount} posts with ${selectionResult.criteriaCount} ICP criteria (persisted). Ask the user to confirm, then call import_leads with provider: "signal-discovery". Criteria are already saved to the campaign.`,
+    };
+}
+export async function setHeadlineICPCriteria(input) {
+    const api = getApi();
+    const { campaignOfferId, headlineICPCriteria, currentStep } = input;
+    // Persist criteria to the campaign so import_leads can rely on backend state.
+    await api.patch(`/api/v3/campaigns/${campaignOfferId}/signal-discovery/posts`, {
+        selectedIds: [],
+        unselectedIds: [],
+        headlineICPCriteria,
+        rubricGuidelines: headlineICPCriteria,
+    });
+    // Update currentStep if provided (via v2 endpoint)
+    if (currentStep) {
+        await api.put(`/api/v2/campaign-offers/${campaignOfferId}`, {
+            currentStep,
+        });
+    }
+    return {
+        success: true,
+        criteriaCount: headlineICPCriteria.length,
+        message: `Prepared ${headlineICPCriteria.length} ICP criteria (persisted). Call import_leads with provider: "signal-discovery". Criteria are already saved to the campaign.`,
+    };
+}