@sellable/mcp 0.1.560 → 0.1.562-phase981.202607110535

package/README.md

@@ -16,8 +16,9 @@ Each message gets 5+ minutes of Claude attention with deep research - no other t
 
 ### Prompt Source Of Truth
 
-There are eight public Sellable entrypoints shared across hosts:
+There are nine public Sellable entrypoints shared across hosts:
 
+- `sellable:find-leads`
 - `sellable:create-campaign`
 - `sellable:create-ab-test`
 - `sellable:create-evergreen-campaigns`
@@ -33,6 +34,11 @@ the approval-gated workflow from:
 
 - `mcp/sellable/skills/create-campaign-v2/SKILL.md`
 
+The find-leads public wrapper builds a live exportable source list without a
+campaign and loads its durable approval-gated workflow from:
+
+- `mcp/sellable/skills/find-leads-v2/SKILL.md`
+
 The create-ab-test public wrapper prepares clean A/B split lead lists and
 review-copy campaigns from:
 
@@ -205,7 +211,7 @@ thread and select `Sellable Create Campaign`, `Sellable Create A/B Test`,
 `Sellable Create Evergreen Campaigns`, `Sellable Foundation`,
 `Sellable Content`, `Sellable Create Post`, `Sellable Refresh Sender Engagement`,
 or `Sellable Refill Sends`; or invoke
-`$sellable:create-campaign`, `$sellable:create-ab-test`,
+`$sellable:find-leads`, `$sellable:create-campaign`, `$sellable:create-ab-test`,
 `$sellable:create-evergreen-campaigns`, `$sellable:foundation`,
 `$sellable:content`, `$sellable:create-post`,
 `$sellable:refresh-sender-engagement`, or `$sellable:refill-sends`. If the app still says
@@ -220,6 +226,7 @@ the Sellable MCP tools for Codex Desktop.
 Use these names consistently:
 
 - Claude Code command: `/sellable:create-campaign`
+- Claude Code command: `/sellable:find-leads`
 - Claude Code command: `/sellable:create-ab-test`
 - Claude Code command: `/sellable:create-evergreen-campaigns`
 - Claude Code command: `/sellable:foundation`
@@ -228,6 +235,7 @@ Use these names consistently:
 - Claude Code command: `/sellable:refresh-sender-engagement`
 - Claude Code command: `/sellable:refill-sends`
 - Codex command: `$sellable:create-campaign`
+- Codex command: `$sellable:find-leads`
 - Codex command: `$sellable:create-ab-test`
 - Codex command: `$sellable:create-evergreen-campaigns`
 - Codex command: `$sellable:foundation`
@@ -237,6 +245,7 @@ Use these names consistently:
 - Codex command: `$sellable:refill-sends`
 - Codex Desktop plugin: `sellable@sellable`
 - Codex visible skill: `Sellable Create Campaign`
+- Codex visible skill: `Sellable Find Leads`
 - Codex visible skill: `Sellable Create A/B Test`
 - Codex visible skill: `Sellable Create Evergreen Campaigns`
 - Codex visible skill: `Sellable Foundation`
@@ -245,6 +254,7 @@ Use these names consistently:
 - Codex visible skill: `Sellable Refresh Sender Engagement`
 - Codex visible skill: `Sellable Refill Sends`
 - Codex skill frontmatter name: `create-campaign`
+- Codex skill frontmatter name: `find-leads`
 - Codex skill frontmatter name: `create-ab-test`
 - Codex skill frontmatter name: `create-evergreen-campaigns`
 - Codex skill frontmatter name: `foundation`
@@ -254,6 +264,7 @@ Use these names consistently:
 - Codex skill frontmatter name: `refill-sends`
 - MCP server name: `sellable`
 - Internal workflow prompt: `create-campaign-v2`
+- Internal workflow prompt: `find-leads-v2`
 - Internal workflow prompt: `refill-sends-workflow`
 - Internal/backward-compatible memory prompt: `interview`
 

package/dist/refill-run-loop.js

@@ -1027,23 +1027,6 @@ async function gatePlan(input, deps, ctx) {
         fallbackSummary: line.fallbackSummary,
     }));
     const fingerprint = fingerprintFromPlan(plan);
-    const approvedTargetShapeRevision = stringValue(input.approval?.targetShapeRevision);
-    if (approvedTargetShapeRevision &&
-        approvedTargetShapeRevision !== fingerprint.targetShapeRevision) {
-        return {
-            status: "blocked",
-            blocker: "scope_drift",
-            runId: ctx.runId,
-            fence: ctx.fence,
-            gate: ctx.gate,
-            guidance: "The canonical refill target shape changed after approval; render a new packet before another primitive.",
-            report: {
-                approvedTargetShapeRevision,
-                freshTargetShapeRevision: fingerprint.targetShapeRevision,
-            },
-            journalPath: ctx.journalPath,
-        };
-    }
     const persistedCircuit = recordValue(runStateProgress(ctx).prepCircuit);
     if (stringValue(action.type) === "prepare_messages" &&
         openCircuitWaits(persistedCircuit, deps.now?.() ?? new Date())) {

package/dist/server.js

@@ -29,6 +29,7 @@ import { getEngageStateTool, setEngageStateTool, } from "./tools/engage-state.js
 import { bulkEnrichWithProspeo, enrichWithProspeo, getProspeoCredits, } from "./tools/enrichment.js";
 import { getRefillPlanV2 } from "./tools/evergreen-refill-plan.js";
 import { getCampaignFramework } from "./tools/framework.js";
+import { bootstrapFindLeads, cancelFindLeads, getFindLeadsRun, reissueFindLeadsWatchLink, updateFindLeadsRun, waitForFindLeadsRun, } from "./tools/find-leads-runs.js";
 import { confirmHarvestJobCompanies, searchHarvestJobs, } from "./tools/harvest-jobs.js";
 import { checkInboxReplyEligibility, getInboxThread, searchInboxThreads, sendInboxDraft, sendInboxManualReply, updateInboxDraft, } from "./tools/inbox.js";
 import { cancelLeadImport, confirmLeadList, confirmProspeoCompanyAccounts, getProviderPrompt, importLeads, listDncEntriesTool, loadCsvDncEntriesTool, loadCsvDomains, loadCsvLinkedinLeads, lookupSalesNavFilter, saveDomainFilters, searchApollo, searchProspeo, searchProspeoCompanies, searchSalesNav, searchSignals, selectPromisingPosts, setHeadlineICPCriteria, } from "./tools/leads.js";
@@ -36,6 +37,7 @@ import { fetchCompany, fetchCompanyPosts, fetchLinkedInPosts, fetchLinkedInProfi
 import { getCampaignNavigationState } from "./tools/navigation.js";
 import { addOnDemandLeads, createOnDemandCampaign, createOnDemandTable, initOnDemandSequence, pauseOnDemandCampaign, startOnDemandCampaign, } from "./tools/one-off.js";
 import { upsertRubric } from "./tools/processing.js";
+import { preflightFindLeadsProvider } from "./tools/provider-preflight.js";
 import { completeSenderResearch, getPostFindLeadsScoutRegistry, getSourceScoutRegistry, getSubskillAsset, getSubskillPrompt, listSubskillPrompts, searchSubskillPrompts, } from "./tools/prompts.js";
 import { waitForCampaignTableReady, waitForLeadListReady, } from "./tools/readiness.js";
 import { refreshSenderEngagementCommand } from "./tools/refresh-sender-engagement.js";
@@ -146,6 +148,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "wait_for_cli_login":
                 result = await handleWaitForCliLogin(args);
                 break;
+            case "bootstrap_find_leads":
+                result = await bootstrapFindLeads(args);
+                break;
+            case "get_find_leads_run":
+                result = await getFindLeadsRun(args);
+                break;
+            case "update_find_leads_run":
+                result = await updateFindLeadsRun(args);
+                break;
+            case "wait_for_find_leads_run":
+                result = await waitForFindLeadsRun(args);
+                break;
+            case "cancel_find_leads":
+                result = await cancelFindLeads(args);
+                break;
+            case "reissue_find_leads_watch_link":
+                result = await reissueFindLeadsWatchLink(args);
+                break;
+            case "preflight_find_leads_provider":
+                result = await preflightFindLeadsProvider(args);
+                break;
             case "bootstrap_engage":
                 result = await bootstrapEngage(args);
                 break;

package/dist/tools/find-leads-runs.d.ts

@@ -0,0 +1,151 @@
+type FindLeadsSnapshot = {
+    runId: string;
+    leadListId?: string;
+    version?: number;
+    status: string;
+    terminal?: boolean;
+    cancelled?: boolean;
+    [key: string]: unknown;
+};
+export declare const findLeadsRunToolDefinitions: readonly [{
+    readonly name: "bootstrap_find_leads";
+    readonly description: "Create or resume a durable campaignless Find Leads run and its lead list. No campaign or workingCampaignId is required.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly bootstrapKey: {
+                readonly type: "string";
+            };
+            readonly name: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["bootstrapKey"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "get_find_leads_run";
+    readonly description: "Read the authoritative durable Find Leads snapshot.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly runId: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["runId"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "update_find_leads_run";
+    readonly description: "Persist a provider/source/import approval receipt using optimistic concurrency.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly runId: {
+                readonly type: "string";
+            };
+            readonly version: {
+                readonly type: "number";
+            };
+            readonly action: {
+                readonly type: "string";
+                readonly enum: readonly ["approve_provider", "approve_source_plan", "approve_import"];
+            };
+            readonly provider: {
+                readonly type: "string";
+                readonly enum: readonly ["sales-nav", "prospeo", "signal-discovery"];
+            };
+            readonly receipt: {
+                readonly type: "object";
+            };
+        };
+        readonly required: readonly ["runId", "version", "action", "receipt"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "wait_for_find_leads_run";
+    readonly description: "Poll durable Find Leads state until it changes or reaches a terminal state. Progress notifications are optional hints only.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly runId: {
+                readonly type: "string";
+            };
+            readonly timeoutMs: {
+                readonly type: "number";
+            };
+            readonly intervalMs: {
+                readonly type: "number";
+            };
+        };
+        readonly required: readonly ["runId"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "cancel_find_leads";
+    readonly description: "Cancel a mutable Find Leads run with its current version.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly runId: {
+                readonly type: "string";
+            };
+            readonly version: {
+                readonly type: "number";
+            };
+        };
+        readonly required: readonly ["runId", "version"];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "reissue_find_leads_watch_link";
+    readonly description: "Rotate and return a fresh one-time live Find Leads watch handoff. Old links are revoked and cannot be reconstructed.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly runId: {
+                readonly type: "string";
+            };
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["claude", "codex", "hermes"];
+            };
+        };
+        readonly required: readonly ["runId"];
+        readonly additionalProperties: false;
+    };
+}];
+export declare function bootstrapFindLeads(input: {
+    bootstrapKey: string;
+    name?: string;
+}): Promise<FindLeadsSnapshot>;
+export declare function getFindLeadsRun(input: {
+    runId: string;
+}): Promise<FindLeadsSnapshot>;
+export declare function updateFindLeadsRun(input: {
+    runId: string;
+    version: number;
+    action: "approve_provider" | "approve_source_plan" | "approve_import";
+    provider?: "sales-nav" | "prospeo" | "signal-discovery";
+    receipt: Record<string, unknown>;
+}): Promise<FindLeadsSnapshot>;
+export declare function cancelFindLeads(input: {
+    runId: string;
+    version: number;
+}): Promise<FindLeadsSnapshot>;
+export declare function reissueFindLeadsWatchLink(input: {
+    runId: string;
+    mode?: "claude" | "codex" | "hermes";
+}): Promise<{
+    runId: string;
+    leadListId: string;
+    watchUrl: string;
+    expiresAt: string;
+}>;
+export declare function waitForFindLeadsRun(input: {
+    runId: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<FindLeadsSnapshot>;
+export {};

package/dist/tools/find-leads-runs.js

@@ -0,0 +1,98 @@
+import { getApi } from "../api.js";
+import { getConfig } from "../auth.js";
+function requestOptions() {
+    const config = getConfig();
+    const workspaceId = config.activeWorkspaceId || config.workspaceId || null;
+    if (!workspaceId) {
+        throw new Error("No active Sellable workspace. Run list_workspaces then set_active_workspace and retry Find Leads.");
+    }
+    return { workspaceId };
+}
+export const findLeadsRunToolDefinitions = [
+    {
+        name: "bootstrap_find_leads",
+        description: "Create or resume a durable campaignless Find Leads run and its lead list. No campaign or workingCampaignId is required.",
+        inputSchema: {
+            type: "object",
+            properties: { bootstrapKey: { type: "string" }, name: { type: "string" } },
+            required: ["bootstrapKey"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_find_leads_run",
+        description: "Read the authoritative durable Find Leads snapshot.",
+        inputSchema: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"], additionalProperties: false },
+    },
+    {
+        name: "update_find_leads_run",
+        description: "Persist a provider/source/import approval receipt using optimistic concurrency.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                runId: { type: "string" }, version: { type: "number" },
+                action: { type: "string", enum: ["approve_provider", "approve_source_plan", "approve_import"] },
+                provider: { type: "string", enum: ["sales-nav", "prospeo", "signal-discovery"] },
+                receipt: { type: "object" },
+            },
+            required: ["runId", "version", "action", "receipt"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "wait_for_find_leads_run",
+        description: "Poll durable Find Leads state until it changes or reaches a terminal state. Progress notifications are optional hints only.",
+        inputSchema: {
+            type: "object",
+            properties: { runId: { type: "string" }, timeoutMs: { type: "number" }, intervalMs: { type: "number" } },
+            required: ["runId"], additionalProperties: false,
+        },
+    },
+    {
+        name: "cancel_find_leads",
+        description: "Cancel a mutable Find Leads run with its current version.",
+        inputSchema: { type: "object", properties: { runId: { type: "string" }, version: { type: "number" } }, required: ["runId", "version"], additionalProperties: false },
+    },
+    {
+        name: "reissue_find_leads_watch_link",
+        description: "Rotate and return a fresh one-time live Find Leads watch handoff. Old links are revoked and cannot be reconstructed.",
+        inputSchema: { type: "object", properties: { runId: { type: "string" }, mode: { type: "string", enum: ["claude", "codex", "hermes"] } }, required: ["runId"], additionalProperties: false },
+    },
+];
+export async function bootstrapFindLeads(input) {
+    return getApi().post("/api/v3/find-leads/runs", input, requestOptions());
+}
+export async function getFindLeadsRun(input) {
+    return getApi().get(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}`, requestOptions());
+}
+export async function updateFindLeadsRun(input) {
+    const kind = input.action === "approve_provider"
+        ? "provider_prompt"
+        : input.action === "approve_source_plan"
+            ? "source_plan"
+            : "import_approval";
+    const provider = input.provider?.replace(/-/g, "_");
+    return getApi().patch(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}`, { action: "record_receipt", version: input.version, kind, receipt: input.receipt, ...(provider ? { provider } : {}) }, requestOptions());
+}
+export async function cancelFindLeads(input) {
+    return getApi().patch(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}`, { action: "cancel", version: input.version }, requestOptions());
+}
+export async function reissueFindLeadsWatchLink(input) {
+    return getApi().post(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}/watch-token`, { mode: input.mode ?? (process.env.CODEX_HOME ? "codex" : "claude") }, requestOptions());
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function waitForFindLeadsRun(input) {
+    const timeoutMs = Math.min(Math.max(input.timeoutMs ?? 55_000, 25), 55_000);
+    const intervalMs = Math.min(Math.max(input.intervalMs ?? 2_000, 1), 10_000);
+    const startedAt = Date.now();
+    let previousVersion;
+    let snapshot = await getFindLeadsRun(input);
+    while (!snapshot.terminal && !snapshot.cancelled && Date.now() - startedAt < timeoutMs) {
+        if (previousVersion !== undefined && snapshot.version !== previousVersion)
+            return snapshot;
+        previousVersion = snapshot.version;
+        await sleep(intervalMs);
+        snapshot = await getFindLeadsRun(input);
+    }
+    return snapshot;
+}