@sellable/mcp 0.1.0

package/dist/tools/rubrics.js

@@ -0,0 +1,681 @@
+import { getApi } from "../api.js";
+import { fetchCampaignRubrics, upsertRubricV3, } from "./processing.js";
+import { getTableRowsMinimal } from "./rows.js";
+const rubricDrafts = new Map();
+const DEFAULT_MAX_PROSPECTS = 5;
+const MAX_PROSPECTS_LIMIT = 25;
+const DEFAULT_TIMEOUT_MS = 90000;
+const DEFAULT_INTERVAL_MS = 2000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeRubricItemDefaults(item) {
+    return {
+        ...item,
+        checkName: item.checkName?.trim(),
+        description: item.description?.trim(),
+        reason: item.reason?.trim(),
+        criterion: item.criterion?.trim() || item.description?.trim(),
+        useCheckForScoring: item.useCheckForScoring !== false,
+        isRequiredCheck: item.isRequiredCheck === true,
+        allowPartialCredit: item.allowPartialCredit !== false,
+        strictMatching: item.strictMatching === true,
+    };
+}
+function assertRubricFields(items) {
+    const invalid = items.filter((item) => !item.checkName || !item.description || !item.reason || !item.criterion);
+    if (invalid.length > 0) {
+        throw new Error("Each rubric item must include checkName, description, criterion, and reason.");
+    }
+}
+function ensureUniqueCheckNames(items) {
+    const seen = new Set();
+    const duplicates = new Set();
+    items.forEach((item) => {
+        if (!item.checkName)
+            return;
+        if (seen.has(item.checkName)) {
+            duplicates.add(item.checkName);
+        }
+        seen.add(item.checkName);
+    });
+    if (duplicates.size > 0) {
+        throw new Error(`Duplicate checkName values found: ${Array.from(duplicates).join(", ")}`);
+    }
+}
+function dedupeRubricsByCheckName(items) {
+    const seen = new Set();
+    const unique = [];
+    items.forEach((item) => {
+        const checkName = item.checkName;
+        if (!checkName) {
+            unique.push(item);
+            return;
+        }
+        if (seen.has(checkName))
+            return;
+        seen.add(checkName);
+        unique.push(item);
+    });
+    return unique;
+}
+function normalizeRubricItems(items) {
+    const normalized = items.map((item) => normalizeRubricItemDefaults(item));
+    ensureUniqueCheckNames(normalized);
+    return normalized;
+}
+function normalizeCampaignRubrics(items) {
+    return normalizeRubricItems(dedupeRubricsByCheckName(items));
+}
+function setDraftRubrics(campaignOfferId, rubrics, source) {
+    const normalized = normalizeRubricItems(rubrics);
+    rubricDrafts.set(campaignOfferId, {
+        campaignOfferId,
+        rubrics: normalized,
+        updatedAt: new Date().toISOString(),
+        source,
+    });
+    return normalized;
+}
+function getDraftRubrics(campaignOfferId) {
+    return rubricDrafts.get(campaignOfferId)?.rubrics ?? null;
+}
+async function fetchCampaignOffer(campaignOfferId) {
+    const v3 = await fetchCampaignRubrics(campaignOfferId);
+    return {
+        workflowTableId: v3.workflowTableId,
+        enableICPFilters: v3.enableICPFilters,
+        leadScoringRubrics: v3.rubrics,
+    };
+}
+async function getRubricsForEdit(campaignOfferId) {
+    const draft = getDraftRubrics(campaignOfferId);
+    if (draft) {
+        return { rubrics: draft, source: "draft" };
+    }
+    const campaign = await fetchCampaignOffer(campaignOfferId);
+    const rubrics = normalizeCampaignRubrics(campaign.leadScoringRubrics || []);
+    setDraftRubrics(campaignOfferId, rubrics, "campaign");
+    return { rubrics, source: "campaign" };
+}
+function resolveMaxProspects(value) {
+    const fallback = DEFAULT_MAX_PROSPECTS;
+    const parsed = typeof value === "number" && !Number.isNaN(value) ? value : fallback;
+    return Math.min(MAX_PROSPECTS_LIMIT, Math.max(1, Math.floor(parsed)));
+}
+function mergeRubricsWithExisting(draftRubrics, existingRubrics) {
+    const existingByCheckName = new Map();
+    existingRubrics.forEach((item) => {
+        if (item.checkName)
+            existingByCheckName.set(item.checkName, item);
+    });
+    const normalizedDraft = normalizeRubricItems(draftRubrics).map((item) => {
+        if (item.id)
+            return item;
+        const existing = item.checkName
+            ? existingByCheckName.get(item.checkName)
+            : undefined;
+        if (existing?.id) {
+            return { ...item, id: existing.id };
+        }
+        return item;
+    });
+    const draftIds = new Set(normalizedDraft.map((item) => item.id).filter(Boolean));
+    const deletedRubricIds = existingRubrics
+        .map((item) => item.id)
+        .filter((id) => Boolean(id))
+        .filter((id) => !draftIds.has(id));
+    return { normalizedDraft, deletedRubricIds };
+}
+function summarizeRubrics(rubrics) {
+    return rubrics.map((rubric) => ({
+        checkName: rubric.checkName,
+        description: rubric.description,
+        id: rubric.id,
+    }));
+}
+function mergeSavedWithUnsaved(savedRubrics, draftRubrics) {
+    if (!savedRubrics)
+        return draftRubrics;
+    const normalizedSaved = normalizeCampaignRubrics(savedRubrics);
+    const unsaved = draftRubrics.filter((rubric) => !rubric.id);
+    return normalizeRubricItems([...normalizedSaved, ...unsaved]);
+}
+export const rubricToolDefinitions = [
+    {
+        name: "draft_rubrics",
+        description: "Generate initial lead scoring rubrics and store them for this campaign. Use save_rubrics to persist.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                leadScoringRubrics: {
+                    type: "array",
+                    description: "Array of rubric criteria",
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string" },
+                            checkName: { type: "string" },
+                            description: { type: "string" },
+                            criterion: { type: "string" },
+                            reason: { type: "string" },
+                            useCheckForScoring: { type: "boolean" },
+                            isRequiredCheck: { type: "boolean" },
+                            allowPartialCredit: { type: "boolean" },
+                            strictMatching: { type: "boolean" },
+                        },
+                        required: ["checkName", "description", "criterion", "reason"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["campaignOfferId", "leadScoringRubrics"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "select_necessary_rubrics",
+        description: "Keep only the required rubric criteria and mark them as required. Use after draft_rubrics.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                requiredCheckNames: {
+                    type: "array",
+                    description: "Array of checkName values to keep and mark as required (1-3 recommended).",
+                    items: { type: "string" },
+                },
+            },
+            required: ["campaignOfferId", "requiredCheckNames"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "save_rubrics",
+        description: "Persist rubric criteria to the campaign. Pass leadScoringRubrics directly to save without drafting. Use update_campaign to enable ICP filtering and change steps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                leadScoringRubrics: {
+                    type: "array",
+                    description: "Optional: pass rubrics directly to save without drafting first. If omitted, reads from draft state.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            checkName: { type: "string" },
+                            description: { type: "string" },
+                            criterion: { type: "string" },
+                            reason: { type: "string" },
+                            isRequiredCheck: { type: "boolean" },
+                            useCheckForScoring: { type: "boolean" },
+                        },
+                    },
+                },
+            },
+            required: ["campaignOfferId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "add_rubric_item",
+        description: "Add a single rubric criterion to the current draft. Call save_rubrics to persist.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                rubric: {
+                    type: "object",
+                    description: "Rubric item to add",
+                    properties: {
+                        checkName: { type: "string" },
+                        description: { type: "string" },
+                        criterion: { type: "string" },
+                        reason: { type: "string" },
+                        useCheckForScoring: { type: "boolean" },
+                        isRequiredCheck: { type: "boolean" },
+                        allowPartialCredit: { type: "boolean" },
+                        strictMatching: { type: "boolean" },
+                    },
+                    required: ["checkName", "description", "criterion", "reason"],
+                    additionalProperties: false,
+                },
+            },
+            required: ["campaignOfferId", "rubric"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "update_rubric_item",
+        description: "Update a single rubric criterion by ID and persist immediately.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                rubricId: {
+                    type: "string",
+                    description: "Rubric item ID to update",
+                },
+                updates: {
+                    type: "object",
+                    description: "Fields to update on the rubric item",
+                    properties: {
+                        checkName: { type: "string" },
+                        description: { type: "string" },
+                        criterion: { type: "string" },
+                        reason: { type: "string" },
+                        useCheckForScoring: { type: "boolean" },
+                        isRequiredCheck: { type: "boolean" },
+                        allowPartialCredit: { type: "boolean" },
+                        strictMatching: { type: "boolean" },
+                    },
+                    additionalProperties: false,
+                },
+            },
+            required: ["campaignOfferId", "rubricId", "updates"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "delete_rubric_item",
+        description: "Delete a single rubric criterion by checkName and persist immediately.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                checkName: {
+                    type: "string",
+                    description: "checkName of the rubric to delete",
+                },
+            },
+            required: ["campaignOfferId", "checkName"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "check_rubric",
+        description: "Queue enrichment + scoring for a sample of prospects (default 7). Requires saved rubrics.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                maxProspects: {
+                    type: "number",
+                    description: `Number of prospects to test (default ${DEFAULT_MAX_PROSPECTS}, max ${MAX_PROSPECTS_LIMIT}).`,
+                },
+            },
+            required: ["campaignOfferId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "wait_for_rubric_results",
+        description: "Wait for ICP rubric pass-rate results to complete for queued prospects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID (used to resolve workflow table)",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Workflow table ID (optional override)",
+                },
+                targetCount: {
+                    type: "number",
+                    description: `Number of completed rubric results to wait for (default ${DEFAULT_MAX_PROSPECTS}).`,
+                },
+                timeoutMs: {
+                    type: "number",
+                    description: `Max time to wait in ms (default ${DEFAULT_TIMEOUT_MS}).`,
+                },
+                intervalMs: {
+                    type: "number",
+                    description: `Polling interval in ms (default ${DEFAULT_INTERVAL_MS}).`,
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+];
+export async function draftRubrics(input) {
+    const rubrics = normalizeRubricItems(input.leadScoringRubrics || []);
+    assertRubricFields(rubrics);
+    const normalized = setDraftRubrics(input.campaignOfferId, rubrics, "draft");
+    return {
+        success: true,
+        message: `Drafted ${normalized.length} rubric criteria. Use save_rubrics to persist to the campaign.`,
+        criteriaCount: normalized.length,
+        criteria: summarizeRubrics(normalized),
+    };
+}
+export async function selectNecessaryRubrics(input) {
+    const { rubrics } = await getRubricsForEdit(input.campaignOfferId);
+    if (rubrics.length === 0) {
+        throw new Error("No rubric criteria found. Use draft_rubrics first to create criteria.");
+    }
+    const existingCheckNames = rubrics.map((r) => r.checkName);
+    const invalidCheckNames = input.requiredCheckNames.filter((name) => !existingCheckNames.includes(name));
+    if (invalidCheckNames.length > 0) {
+        throw new Error(`Invalid checkName(s): ${invalidCheckNames.join(", ")}. Available: ${existingCheckNames.join(", ")}`);
+    }
+    const updatedRubrics = rubrics
+        .filter((rubric) => input.requiredCheckNames.includes(rubric.checkName))
+        .map((rubric) => ({
+        ...rubric,
+        isRequiredCheck: true,
+        useCheckForScoring: true,
+    }));
+    setDraftRubrics(input.campaignOfferId, updatedRubrics, "draft");
+    return {
+        success: true,
+        message: `Kept ${updatedRubrics.length} required criteria and removed ${rubrics.length - updatedRubrics.length} non-essential ones. Use save_rubrics to persist changes.`,
+        requiredCount: updatedRubrics.length,
+        deletedCount: rubrics.length - updatedRubrics.length,
+        requiredChecks: updatedRubrics.map((r) => r.checkName),
+    };
+}
+export async function addRubricItem(input) {
+    const { rubrics } = await getRubricsForEdit(input.campaignOfferId);
+    const nextRubric = normalizeRubricItemDefaults(input.rubric);
+    assertRubricFields([nextRubric]);
+    if (rubrics.some((r) => r.checkName === nextRubric.checkName)) {
+        throw new Error(`Rubric criterion "${nextRubric.checkName}" already exists. Use update_rubric_item instead.`);
+    }
+    const updatedRubrics = [...rubrics, nextRubric];
+    setDraftRubrics(input.campaignOfferId, updatedRubrics, "draft");
+    return {
+        success: true,
+        message: `Added "${nextRubric.checkName}" criterion. Now ${updatedRubrics.length} total criteria. Use save_rubrics to persist to the campaign.`,
+        totalCriteria: updatedRubrics.length,
+        criteria: summarizeRubrics(updatedRubrics),
+    };
+}
+export async function updateRubricItem(input) {
+    const { rubrics } = await getRubricsForEdit(input.campaignOfferId);
+    const rubricIndex = rubrics.findIndex((r) => r.id === input.rubricId);
+    if (rubricIndex === -1) {
+        const availableIds = rubrics
+            .map((r) => r.id)
+            .filter((id) => Boolean(id));
+        throw new Error(`Rubric item with ID ${input.rubricId} not found. Available IDs: ${availableIds.join(", ")}`);
+    }
+    const updatedRubrics = [...rubrics];
+    updatedRubrics[rubricIndex] = normalizeRubricItemDefaults({
+        ...updatedRubrics[rubricIndex],
+        ...input.updates,
+    });
+    ensureUniqueCheckNames(updatedRubrics);
+    assertRubricFields([updatedRubrics[rubricIndex]]);
+    const result = await upsertRubricV3({
+        campaignOfferId: input.campaignOfferId,
+        upsert: [updatedRubrics[rubricIndex]],
+    });
+    const mergedDraft = mergeSavedWithUnsaved(result?.rubrics, updatedRubrics);
+    setDraftRubrics(input.campaignOfferId, mergedDraft, "draft");
+    return {
+        success: true,
+        message: `Updated rubric criterion "${updatedRubrics[rubricIndex].checkName}"`,
+        rubricId: input.rubricId,
+        updatedFields: Object.keys(input.updates || {}),
+    };
+}
+export async function deleteRubricItem(input) {
+    const { rubrics } = await getRubricsForEdit(input.campaignOfferId);
+    const rubricToDelete = rubrics.find((r) => r.checkName === input.checkName);
+    if (!rubricToDelete) {
+        throw new Error(`Rubric criterion "${input.checkName}" not found. Available: ${rubrics
+            .map((r) => r.checkName)
+            .join(", ")}`);
+    }
+    const updatedRubrics = rubrics.filter((r) => r.checkName !== input.checkName);
+    if (!rubricToDelete.id) {
+        setDraftRubrics(input.campaignOfferId, updatedRubrics, "draft");
+        return {
+            success: true,
+            message: `Deleted "${input.checkName}" criterion. Now ${updatedRubrics.length} total criteria. (Not saved yet)`,
+            totalCriteria: updatedRubrics.length,
+            deletedFromDatabase: false,
+        };
+    }
+    const result = await upsertRubricV3({
+        campaignOfferId: input.campaignOfferId,
+        upsert: [],
+        deleteIds: [rubricToDelete.id],
+    });
+    const mergedDraft = mergeSavedWithUnsaved(result?.rubrics, updatedRubrics);
+    setDraftRubrics(input.campaignOfferId, mergedDraft, "draft");
+    return {
+        success: true,
+        message: `Deleted "${input.checkName}" criterion. Now ${updatedRubrics.length} total criteria.`,
+        totalCriteria: updatedRubrics.length,
+        deletedFromDatabase: true,
+    };
+}
+export async function saveRubrics(input) {
+    // If rubrics passed directly, use them (skip draft state)
+    let rubrics;
+    if (input.leadScoringRubrics && input.leadScoringRubrics.length > 0) {
+        rubrics = normalizeRubricItems(input.leadScoringRubrics);
+        assertRubricFields(rubrics);
+        setDraftRubrics(input.campaignOfferId, rubrics, "draft");
+    }
+    else {
+        ({ rubrics } = await getRubricsForEdit(input.campaignOfferId));
+    }
+    if (rubrics.length === 0) {
+        throw new Error("No rubric criteria to save. Pass leadScoringRubrics or call draft_rubrics first.");
+    }
+    const activeRubrics = rubrics.filter((r) => r.useCheckForScoring !== false);
+    if (activeRubrics.length === 0) {
+        throw new Error("No active rubric criteria found.");
+    }
+    assertRubricFields(activeRubrics);
+    const campaign = await fetchCampaignOffer(input.campaignOfferId);
+    const existingRubrics = normalizeCampaignRubrics(campaign.leadScoringRubrics || []);
+    const { normalizedDraft, deletedRubricIds } = mergeRubricsWithExisting(activeRubrics, existingRubrics);
+    const result = await upsertRubricV3({
+        campaignOfferId: input.campaignOfferId,
+        upsert: normalizedDraft,
+        deleteIds: deletedRubricIds,
+    });
+    if (result?.rubrics) {
+        setDraftRubrics(input.campaignOfferId, result.rubrics, "campaign");
+    }
+    else {
+        setDraftRubrics(input.campaignOfferId, normalizedDraft, "draft");
+    }
+    // Auto-enable ICP filtering on the campaign when rubrics are saved.
+    // The PUT triggers syncCampaignTableIcpFiltering on the server, which is
+    // the only path that updates the workflow table's Enable ICP Filtering
+    // column config + cells to true. Always fire the PUT even if
+    // CampaignOffer.enableICPFilters is already true: create_campaign pre-sets
+    // that server flag, but the workflow table column is created later with
+    // inputMapping.value.value=false by default, so the column never syncs
+    // without this call. Observed on Phase 95 live UAT: Skillsync + Patientdesk
+    // both had CampaignOffer.enableICPFilters=true but Enable ICP Filtering
+    // column cells=false → ICP Score runCondition evaluated false → entire
+    // cascade blocked.
+    let enableICPFiltersSet = false;
+    try {
+        const api = getApi();
+        await api.put(`/api/v2/campaign-offers/${input.campaignOfferId}`, {
+            enableICPFilters: true,
+        });
+        enableICPFiltersSet = true;
+    }
+    catch (error) {
+        // Non-fatal: the rubric save already succeeded. Log and
+        // let the caller fix the flag via update_campaign if needed.
+        console.error("[save_rubrics] Could not auto-enable ICP filtering on campaign", input.campaignOfferId, error);
+    }
+    return {
+        success: true,
+        message: enableICPFiltersSet || campaign.enableICPFilters === true
+            ? `Saved ${normalizedDraft.length} rubric criteria and ICP filtering is ON.`
+            : `Saved ${normalizedDraft.length} rubric criteria to the campaign. WARNING: could not auto-enable ICP filtering — call update_campaign({ campaignId, enableICPFilters: true }) to activate rubric-based filtering.`,
+        criteriaCount: normalizedDraft.length,
+        deletedCount: deletedRubricIds.length,
+        enableICPFiltersSet,
+    };
+}
+export async function checkRubric(input) {
+    const maxProspects = resolveMaxProspects(input.maxProspects);
+    const campaign = await fetchCampaignOffer(input.campaignOfferId);
+    if (campaign.enableICPFilters !== true) {
+        throw new Error("ICP filtering is not enabled. Save and apply rubrics before running check_rubric.");
+    }
+    const draft = getDraftRubrics(input.campaignOfferId);
+    const rubrics = normalizeCampaignRubrics((draft || campaign.leadScoringRubrics || []).filter((r) => r.useCheckForScoring !== false));
+    if (rubrics.length === 0) {
+        throw new Error("No active rubric criteria found. Use draft_rubrics and save_rubrics first.");
+    }
+    const unsavedRubrics = rubrics.filter((r) => !r.id);
+    if (unsavedRubrics.length > 0) {
+        throw new Error(`${unsavedRubrics.length} rubric criteria are not saved to database. Call save_rubrics before check_rubric.`);
+    }
+    const workflowTableId = campaign.workflowTableId;
+    if (!workflowTableId) {
+        throw new Error("No workflow table found. Complete the Find Leads step first to create a workflow table with leads.");
+    }
+    const api = getApi();
+    const tableResponse = await api.get(`/api/v3/campaigns/${input.campaignOfferId}/workflow-table`);
+    const workflowTable = tableResponse.workflowTable;
+    if (!workflowTable) {
+        throw new Error("Workflow table not found for this campaign.");
+    }
+    const enrichColumn = workflowTable.columns?.find((col) => col.columnType === "enrich_person");
+    if (!enrichColumn) {
+        throw new Error("No Enrich Person column found in workflow table. The table may not be set up correctly.");
+    }
+    const rows = workflowTable.rows || [];
+    const cellsToQueue = [];
+    for (const row of rows) {
+        if (cellsToQueue.length >= maxProspects)
+            break;
+        const enrichCell = row.cells?.find((cell) => cell.columnId === enrichColumn.id);
+        if (!enrichCell)
+            continue;
+        const queueableStatuses = ["pending", "error", "dependency_blocked"];
+        if (queueableStatuses.includes(enrichCell.status || "")) {
+            cellsToQueue.push(enrichCell.id);
+        }
+    }
+    if (cellsToQueue.length === 0) {
+        return {
+            success: true,
+            message: "No rows need processing. All enrich cells are either completed, cached, or currently processing.",
+            processedRows: 0,
+            tableId: workflowTable.id,
+        };
+    }
+    // Use the same robust batch queue path as Launch "Enrich All":
+    // atomically queue + dispatch with lock protection.
+    const queueResult = await api.post(`/api/v3/workflow-tables/cells/queue-batch`, {
+        tableId: workflowTable.id,
+        cellIds: cellsToQueue,
+    });
+    const queuedCount = queueResult?.queued ?? 0;
+    const failedCount = queueResult?.failed ?? 0;
+    const skippedCount = queueResult?.skipped ?? 0;
+    const dispatchedCount = queueResult?.dispatched ?? queuedCount;
+    return {
+        success: true,
+        message: `Queued ${queuedCount} prospects for enrichment and scoring.${failedCount > 0 ? ` (${failedCount} failed to dispatch)` : ""}`,
+        processedRows: queuedCount,
+        queuedCount,
+        dispatchedCount,
+        failedCount,
+        skippedCount,
+        tableId: workflowTable.id,
+    };
+}
+export async function waitForRubricResults(input) {
+    const api = getApi();
+    const timeoutMs = Math.max(5000, input.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const intervalMs = Math.max(500, input.intervalMs ?? DEFAULT_INTERVAL_MS);
+    const targetCount = resolveMaxProspects(input.targetCount);
+    let tableId = input.tableId;
+    if (!tableId && input.campaignOfferId) {
+        const campaign = await fetchCampaignOffer(input.campaignOfferId);
+        tableId = campaign.workflowTableId ?? undefined;
+    }
+    if (!tableId) {
+        throw new Error("Workflow table ID is required. Provide tableId or campaignOfferId.");
+    }
+    const start = Date.now();
+    let attempts = 0;
+    let lastStats = null;
+    while (Date.now() - start <= timeoutMs) {
+        attempts += 1;
+        const stats = await api.get(`/api/v3/workflow-tables/${tableId}/stats`);
+        lastStats = stats;
+        const completed = stats.passRate?.completed ?? 0;
+        const totalRows = stats.totalRows ?? 0;
+        const effectiveTarget = totalRows > 0 ? Math.min(targetCount, totalRows) : targetCount;
+        if (completed >= effectiveTarget) {
+            const passed = stats.passRate?.passed ?? 0;
+            const percent = completed > 0 ? Math.round((passed / completed) * 100) : 0;
+            // Fetch current row states so caller sees per-row enrich/ICP status
+            const rowSnapshot = await getTableRowsMinimal(tableId, {
+                limit: effectiveTarget,
+            });
+            return {
+                ready: true,
+                attempts,
+                elapsedMs: Date.now() - start,
+                tableId,
+                passRate: {
+                    completed,
+                    passed,
+                    percent,
+                    targetCount: effectiveTarget,
+                },
+                rows: rowSnapshot.rows,
+                stats,
+            };
+        }
+        await sleep(intervalMs);
+    }
+    const completed = lastStats?.passRate?.completed ?? 0;
+    const passed = lastStats?.passRate?.passed ?? 0;
+    const percent = completed > 0 ? Math.round((passed / completed) * 100) : 0;
+    return {
+        ready: false,
+        reason: "timeout",
+        attempts,
+        elapsedMs: Date.now() - start,
+        tableId,
+        passRate: {
+            completed,
+            passed,
+            percent,
+            targetCount,
+        },
+        stats: lastStats,
+    };
+}