@sellable/mcp 0.1.31 → 0.1.33

package/dist/tools/cli-login.d.ts

@@ -0,0 +1,86 @@
+export declare const __TEST_INTERNALS__: {
+    POLL_INTERVAL_MS: number;
+    DEFAULT_TIMEOUT_MS: number;
+    TOOL_CALL_TIMEOUT_GUARD_MS: number;
+    MAX_NETWORK_RETRIES: number;
+};
+export type StartCliLoginInput = {
+    email: string;
+};
+export type WaitForCliLoginInput = {
+    sessionId: string;
+    /** Override outer session budget (ms). Default 5 minutes. Clamped to DEFAULT_TIMEOUT_MS. */
+    timeoutMs?: number;
+    /** Test-only: override the 55s tool-call host-cap guard. Not exposed in inputSchema. */
+    toolGuardMs?: number;
+    /** Test-only: override poll interval. Not exposed in inputSchema. */
+    pollIntervalMs?: number;
+};
+type CliLoginErrorType = "rate_limited" | "send_failed" | "expired" | "already_consumed" | "timeout" | "tool_timeout_guard" | "network_error" | "not_implemented";
+type CliLoginErrorPayload = {
+    ok: false;
+    error: {
+        type: CliLoginErrorType;
+        message: string;
+        guidance: string;
+    };
+};
+type StartCliLoginSuccess = {
+    ok: true;
+    sessionId: string;
+    confirmUrl: string;
+    expiresInSec: number;
+    /** Locked verbatim string the agent shows the user. */
+    humanMessage: string;
+};
+type WaitForCliLoginSuccess = {
+    ok: true;
+    activeWorkspaceId: string;
+    activeWorkspaceName?: string;
+    configPath: string;
+    /**
+     * True if the server reused the user's existing default workspace
+     * (vs creating a new one). The skill uses this to branch the
+     * post-auth greeting copy.
+     */
+    isReturningUser: boolean;
+    /** Locked verbatim string the agent shows the user. */
+    humanMessage: string;
+};
+export declare const startCliLoginToolDef: {
+    readonly name: "start_cli_login";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly email: {
+                readonly type: "string";
+                readonly description: "User's email — magic link is sent here.";
+            };
+        };
+        readonly required: readonly ["email"];
+        readonly additionalProperties: false;
+    };
+};
+export declare const waitForCliLoginToolDef: {
+    readonly name: "wait_for_cli_login";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly sessionId: {
+                readonly type: "string";
+                readonly description: "Session ID from start_cli_login.";
+            };
+            readonly timeoutMs: {
+                readonly type: "number";
+                readonly description: "Outer session budget (ms). Default 300000 (5min). Clamped at 5min.";
+            };
+        };
+        readonly required: readonly ["sessionId"];
+        readonly additionalProperties: false;
+    };
+};
+export declare function handleStartCliLogin(args: StartCliLoginInput): Promise<StartCliLoginSuccess | CliLoginErrorPayload>;
+export declare function handleWaitForCliLogin(args: WaitForCliLoginInput): Promise<WaitForCliLoginSuccess | CliLoginErrorPayload>;
+export {};

package/dist/tools/cli-login.js

@@ -0,0 +1,208 @@
+import { writeNewConfig } from "../auth.js";
+/**
+ * Sellable CLI login tools.
+ *
+ * Two-phase magic-link handoff used by the create-campaign skill when a
+ * brand-new user has no `~/.sellable/config.json` yet:
+ *
+ *   1. start_cli_login({ email })
+ *      → POSTs to /api/v3/cli-session, server emails a magic link.
+ *
+ *   2. wait_for_cli_login({ sessionId })
+ *      → Polls /api/v3/cli-session/[id]/poll every 2s until the user clicks
+ *        the link, completes browser auth, and the server transitions the
+ *        session to status="ready". Persists the resulting token via
+ *        writeNewConfig().
+ *
+ * Constants:
+ *   POLL_INTERVAL_MS         — 2s between polls
+ *   DEFAULT_TIMEOUT_MS       — 5min outer session budget (matches CliSession TTL)
+ *   TOOL_CALL_TIMEOUT_GUARD  — 55s, mirrors mcp/sellable/src/tools/readiness.ts:31.
+ *                              MCP hosts (esp. Claude Code) cap individual tool
+ *                              calls at ~60s; without this guard the host kills
+ *                              the loop before our outer 5min budget elapses.
+ *                              Agent re-invokes wait_for_cli_login with the SAME
+ *                              sessionId on tool_timeout_guard until the outer
+ *                              budget runs out or sign-in completes.
+ *
+ * Security:
+ *   No tool here logs `confirmUrl`, the plaintext token, or `sessionId`.
+ *   See Phase 116 RESEARCH.md Pitfall 6.
+ */
+const POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const TOOL_CALL_TIMEOUT_GUARD_MS = 55_000;
+const MAX_NETWORK_RETRIES = 3;
+// Exposed for tests so the 55s guard doesn't cause real-time waits.
+export const __TEST_INTERNALS__ = {
+    POLL_INTERVAL_MS,
+    DEFAULT_TIMEOUT_MS,
+    TOOL_CALL_TIMEOUT_GUARD_MS,
+    MAX_NETWORK_RETRIES,
+};
+function errorPayload(type, message, guidance) {
+    return { ok: false, error: { type, message, guidance } };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Resolve API base URL for the un-authed handoff. Matches the resolution chain
+ * documented in Plan 09 UAT step 1: env override > production default. We do
+ * NOT auto-read a partial ~/.sellable/config.json here — that's an
+ * over-engineering trap for a single edge case fully addressed by an env-var
+ * doc.
+ */
+function resolveApiUrl() {
+    return (process.env.SELLABLE_API_URL ??
+        process.env.SELLABLE_BASE_URL ??
+        "https://app.sellable.dev");
+}
+export const startCliLoginToolDef = {
+    name: "start_cli_login",
+    description: "Start the CLI login handoff. Triggers a magic-link email to the supplied email address. " +
+        "Returns the confirm URL the user will be redirected to after clicking the link. " +
+        "Pair with wait_for_cli_login to block until the user finishes browser sign-in.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            email: {
+                type: "string",
+                description: "User's email — magic link is sent here.",
+            },
+        },
+        required: ["email"],
+        additionalProperties: false,
+    },
+};
+export const waitForCliLoginToolDef = {
+    name: "wait_for_cli_login",
+    description: "Poll the CLI login session every 2s until the user finishes browser sign-in or 5 minutes elapse. " +
+        "On success, writes ~/.sellable/config.json so subsequent MCP calls are authenticated. " +
+        "Re-call with the SAME sessionId on tool_timeout_guard — do NOT call start_cli_login again.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sessionId: {
+                type: "string",
+                description: "Session ID from start_cli_login.",
+            },
+            timeoutMs: {
+                type: "number",
+                description: "Outer session budget (ms). Default 300000 (5min). Clamped at 5min.",
+            },
+        },
+        required: ["sessionId"],
+        additionalProperties: false,
+    },
+};
+export async function handleStartCliLogin(args) {
+    const apiUrl = resolveApiUrl();
+    let res;
+    try {
+        res = await fetch(`${apiUrl}/api/v3/cli-session`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ email: args.email }),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return errorPayload("network_error", "Could not reach Sellable to start CLI login.", `Check your internet connection, then retry. Underlying error: ${message.slice(0, 200)}`);
+    }
+    if (res.status === 429) {
+        return errorPayload("rate_limited", "Too many login attempts in the last minute. Wait 60s and try again.", "Magic-link signups are rate-limited per IP to 10 per minute. This is normal during testing.");
+    }
+    if (!res.ok) {
+        let detail = "";
+        try {
+            detail = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        return errorPayload("send_failed", "Could not start CLI login.", detail.slice(0, 500) ||
+            `Server returned ${res.status}. Try again or contact support.`);
+    }
+    const body = (await res.json());
+    // SECURITY: do NOT log body.confirmUrl, body.sessionId, or any token.
+    return {
+        ok: true,
+        sessionId: body.sessionId,
+        confirmUrl: body.confirmUrl,
+        expiresInSec: body.expiresInSec,
+        humanMessage: `Magic link sent to ${args.email}. Click it from your inbox — I'll wait. (If your team already has a Sellable workspace, ask an admin to invite you instead — that gets you straight into their data.)`,
+    };
+}
+export async function handleWaitForCliLogin(args) {
+    const timeoutMs = Math.min(args.timeoutMs ?? DEFAULT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS);
+    const toolGuardMs = args.toolGuardMs ?? TOOL_CALL_TIMEOUT_GUARD_MS;
+    const pollIntervalMs = args.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const apiUrl = resolveApiUrl();
+    const startedAt = Date.now();
+    const work = (async () => {
+        let consecutiveNetworkFailures = 0;
+        while (Date.now() - startedAt < timeoutMs) {
+            let res;
+            try {
+                res = await fetch(`${apiUrl}/api/v3/cli-session/${args.sessionId}/poll`);
+                consecutiveNetworkFailures = 0;
+            }
+            catch (err) {
+                consecutiveNetworkFailures += 1;
+                if (consecutiveNetworkFailures >= MAX_NETWORK_RETRIES) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return errorPayload("network_error", "Lost connection to Sellable while waiting for sign-in.", `Tried ${MAX_NETWORK_RETRIES} times. Check your internet and retry. Underlying error: ${message.slice(0, 200)}`);
+                }
+                await sleep(pollIntervalMs);
+                continue;
+            }
+            if (res.status === 410) {
+                return errorPayload("expired", "That magic link expired.", "Run /sellable:create-campaign again to retry.");
+            }
+            if (!res.ok) {
+                // Transient — back off and retry
+                await sleep(pollIntervalMs);
+                continue;
+            }
+            let body;
+            try {
+                body = (await res.json());
+            }
+            catch {
+                await sleep(pollIntervalMs);
+                continue;
+            }
+            if (body.status === "ready") {
+                const { configPath } = writeNewConfig({
+                    token: body.token,
+                    activeWorkspaceId: body.activeWorkspaceId,
+                    activeWorkspaceName: body.activeWorkspaceName,
+                    apiUrl: body.apiUrl,
+                });
+                return {
+                    ok: true,
+                    activeWorkspaceId: body.activeWorkspaceId,
+                    ...(body.activeWorkspaceName
+                        ? { activeWorkspaceName: body.activeWorkspaceName }
+                        : {}),
+                    configPath,
+                    isReturningUser: body.isReturningUser ?? false,
+                    humanMessage: "Signed in. Continuing.",
+                };
+            }
+            if (body.status === "claimed") {
+                return errorPayload("already_consumed", "Login already completed in another window.", "Your terminal config has been written; try the next step.");
+            }
+            // status === 'pending' — keep polling
+            await sleep(pollIntervalMs);
+        }
+        return errorPayload("timeout", "Login timed out after 5 minutes.", "Run /sellable:create-campaign again, or paste the manual fallback shown in the browser.");
+    })();
+    const guard = new Promise((resolve) => {
+        setTimeout(() => {
+            resolve(errorPayload("tool_timeout_guard", "Tool call hit the 55s host-cap guard.", "Re-call wait_for_cli_login with the SAME sessionId — the underlying CliSession is still pending; this does NOT create a new session."));
+        }, toolGuardMs).unref?.();
+    });
+    return Promise.race([work, guard]);
+}

package/dist/tools/flow-preflight.d.ts

@@ -13,7 +13,7 @@ type SenderEnrichmentSnapshot = {
     hasCaseStudies: boolean;
     hasProof: boolean;
 };
-type SenderResearchDepth = "minimal-verification" | "deep-proof";
+type SenderResearchDepth = "minimal-verification" | "deep-proof" | "parallel-batch";
 export declare function markCreateCampaignPromptLoaded(): CreateCampaignPromptPreflightState;
 export declare function markResearchPromptLoaded(mode?: ResearchPromptMode, subskillName?: string): ResearchPromptPreflightState;
 export declare function markSenderEnrichmentObserved(input: {
@@ -48,21 +48,8 @@ export declare function assertResearchPromptLoaded(mode?: ResearchPromptMode | "
 };
 export declare function assertNetNewCreateCampaignResearchReady(): {
     readonly ok: true;
-    readonly enrichmentStatus: "partial" | "complete";
-    readonly hasCaseStudies: boolean;
-    readonly hasProof: boolean;
-    readonly enrichmentLooksComplete: boolean;
-    readonly usedResearchPrompt: boolean;
-    readonly researchPromptMode: ResearchPromptMode;
-    readonly researchPromptSubskillName: string;
-    readonly researchCompletion: {
-        readonly depth: SenderResearchDepth;
-        readonly proofItemsFound: number;
-        readonly caseStudyItemsFound: number;
-        readonly credibilitySignalsFound: number;
-        readonly completedAt: string;
-    };
-    readonly needsResearch: true;
+    readonly senderResearchPromptLoadedAt: string;
+    readonly senderResearchCompletedAt: string;
 };
 export declare function resetFlowPreflightState(): void;
 export {};

package/dist/tools/flow-preflight.js

@@ -93,40 +93,21 @@ export function assertResearchPromptLoaded(mode = "any") {
     throw new Error("FLOW_PRECONDITION: research preload missing. Call get_subskill_prompt with the matching research wrapper (research-sender or research-prospect), then run research before continuing.");
 }
 export function assertNetNewCreateCampaignResearchReady() {
-    if (!senderEnrichmentSnapshot) {
-        throw new Error("FLOW_PRECONDITION: net-new create_campaign requires sender enrichment context. Call enrich_sender first.");
-    }
-    const enrichmentLooksComplete = senderEnrichmentSnapshot.enrichmentStatus === "complete" &&
-        senderEnrichmentSnapshot.hasCaseStudies &&
-        senderEnrichmentSnapshot.hasProof;
     const senderResearchPromptState = researchPromptStates.sender;
     if (!senderResearchPromptState) {
-        throw new Error('FLOW_PRECONDITION: net-new create_campaign requires sender research after enrich_sender. Call get_subskill_prompt({ subskillName: "research-sender" }) and run sender research before create_campaign.');
+        throw new Error('FLOW_PRECONDITION: net-new create_campaign requires sender research preload. Call get_subskill_prompt({ subskillName: "research-sender" }) and run sender research before create_campaign.');
     }
     if (!senderResearchCompletionState) {
-        throw new Error("FLOW_PRECONDITION: completed sender research is required before create_campaign. After running research-sender, call complete_sender_research({ depth, proofItemsFound, caseStudyItemsFound, credibilitySignalsFound, notes? }).");
+        throw new Error("FLOW_PRECONDITION: completed sender research is required before create_campaign. After running research-sender (parallel batch of fetch_linkedin_profile + fetch_company + WebSearches), call complete_sender_research({ depth, proofItemsFound, caseStudyItemsFound, credibilitySignalsFound, notes? }).");
     }
     if (new Date(senderResearchCompletionState.completedAt).getTime() <
-        new Date(senderEnrichmentSnapshot.observedAt).getTime()) {
-        throw new Error("FLOW_PRECONDITION: sender research completion is stale for the latest enrichment. Rerun research-sender after enrich_sender, then call complete_sender_research before create_campaign.");
+        new Date(senderResearchPromptState.loadedAt).getTime()) {
+        throw new Error("FLOW_PRECONDITION: sender research completion is older than the latest research-sender prompt load. Re-run sender research and call complete_sender_research again.");
     }
     return {
         ok: true,
-        enrichmentStatus: senderEnrichmentSnapshot.enrichmentStatus,
-        hasCaseStudies: senderEnrichmentSnapshot.hasCaseStudies,
-        hasProof: senderEnrichmentSnapshot.hasProof,
-        enrichmentLooksComplete,
-        usedResearchPrompt: Boolean(senderResearchPromptState),
-        researchPromptMode: senderResearchPromptState?.mode ?? null,
-        researchPromptSubskillName: senderResearchPromptState?.subskillName ?? null,
-        researchCompletion: {
-            depth: senderResearchCompletionState.depth,
-            proofItemsFound: senderResearchCompletionState.proofItemsFound,
-            caseStudyItemsFound: senderResearchCompletionState.caseStudyItemsFound,
-            credibilitySignalsFound: senderResearchCompletionState.credibilitySignalsFound,
-            completedAt: senderResearchCompletionState.completedAt,
-        },
-        needsResearch: true,
+        senderResearchPromptLoadedAt: senderResearchPromptState.loadedAt,
+        senderResearchCompletedAt: senderResearchCompletionState.completedAt,
     };
 }
 export function resetFlowPreflightState() {

package/dist/tools/linkedin.d.ts

@@ -15,6 +15,7 @@ export declare const linkedinToolDefinitions: ({
             };
             postUrl?: undefined;
             sources?: undefined;
+            full?: undefined;
             companyUrl?: undefined;
             sortBy?: undefined;
             linkedin_url?: undefined;
@@ -44,6 +45,7 @@ export declare const linkedinToolDefinitions: ({
                 default: number;
             };
             linkedinUrl?: undefined;
+            full?: undefined;
             companyUrl?: undefined;
             sortBy?: undefined;
             linkedin_url?: undefined;
@@ -61,6 +63,11 @@ export declare const linkedinToolDefinitions: ({
                 type: string;
                 description: string;
             };
+            full: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
             limit?: undefined;
             postUrl?: undefined;
             sources?: undefined;
@@ -85,6 +92,7 @@ export declare const linkedinToolDefinitions: ({
             limit?: undefined;
             postUrl?: undefined;
             sources?: undefined;
+            full?: undefined;
             sortBy?: undefined;
             linkedin_url?: undefined;
             max_posts?: undefined;
@@ -115,6 +123,7 @@ export declare const linkedinToolDefinitions: ({
             linkedinUrl?: undefined;
             postUrl?: undefined;
             sources?: undefined;
+            full?: undefined;
             linkedin_url?: undefined;
             max_posts?: undefined;
         };
@@ -139,6 +148,7 @@ export declare const linkedinToolDefinitions: ({
             limit?: undefined;
             postUrl?: undefined;
             sources?: undefined;
+            full?: undefined;
             companyUrl?: undefined;
             sortBy?: undefined;
         };
@@ -158,6 +168,7 @@ export declare const linkedinToolDefinitions: ({
             limit?: undefined;
             postUrl?: undefined;
             sources?: undefined;
+            full?: undefined;
             companyUrl?: undefined;
             sortBy?: undefined;
             max_posts?: undefined;
@@ -177,7 +188,9 @@ export declare function fetchLinkedInPosts(linkedinUrl: string, limit?: number):
     posts: SerializedPost[];
     count: number;
 }>;
-export declare function fetchLinkedInProfile(linkedinUrl: string): Promise<unknown>;
+export declare function fetchLinkedInProfile(linkedinUrl: string, options?: {
+    full?: boolean;
+}): Promise<unknown>;
 export declare function fetchCompany(companyUrl: string): Promise<unknown>;
 export declare function fetchCompanyPosts(companyUrl: string, limit?: number, sortBy?: "recent" | "top"): Promise<{
     posts: SerializedPost[];

package/dist/tools/linkedin.js

@@ -46,7 +46,7 @@ export const linkedinToolDefinitions = [
     },
     {
         name: "fetch_linkedin_profile",
-        description: "Fetch LinkedIn profile details from Sellable scrape endpoints.",
+        description: "Fetch LinkedIn profile details. Defaults to the cheaper 'main' payload — same envelope shape with most-recent role, headline, about, location, education, top skills, certifications, languages, projects, etc. Pass full=true ONLY when you need the long-tail experience history (positions 6+) or complete skill list (skills 3+) for deep research. Most personalization, qualification, and outreach use cases work with main; reach for full only when the user explicitly asks for full work history or comprehensive skill audit.",
         inputSchema: {
             type: "object",
             properties: {
@@ -54,6 +54,11 @@ export const linkedinToolDefinitions = [
                     type: "string",
                     description: "Full LinkedIn profile URL",
                 },
+                full: {
+                    type: "boolean",
+                    description: "Opt into the full payload (~38% more expensive, slightly slower). Set true only when you specifically need the long-tail experience history or full skill list. Default false (main payload).",
+                    default: false,
+                },
             },
             required: ["linkedinUrl"],
         },
@@ -152,9 +157,12 @@ export async function fetchLinkedInPosts(linkedinUrl, limit = 25) {
         count: posts.length,
     };
 }
-export async function fetchLinkedInProfile(linkedinUrl) {
+export async function fetchLinkedInProfile(linkedinUrl, options = {}) {
     const api = getApi();
     const params = new URLSearchParams({ linkedinUrl });
+    if (options.full) {
+        params.set("full", "true");
+    }
     return api.get(`/api/v1/scrape/linkedin/profile?${params.toString()}`);
 }
 export async function fetchCompany(companyUrl) {

package/dist/tools/navigation.js

@@ -138,8 +138,8 @@ function checkCampaignCreated(campaign) {
     const missing = [];
     if (!campaign.id)
         missing.push("campaignId");
-    if (!campaign.clientProspectId)
-        missing.push("clientProspectId");
+    // Phase 114: clientProspectId is optional. A persisted campaign without
+    // clientProspectId is a valid Phase-114 net-new campaign.
     if (!getBriefContent(campaign.campaignBrief).trim()) {
         missing.push("campaignBrief.content");
     }

package/dist/tools/one-off.d.ts

@@ -1,7 +1,8 @@
 export type CreateOnDemandTableInput = {
     name: string;
     senderIds?: string[];
-    clientProspectId: string;
+    clientProspectId?: string;
+    senderLinkedinUrl?: string;
     offerPositioning?: Record<string, unknown>;
     campaignBrief?: unknown;
 };
@@ -26,7 +27,8 @@ export type InitOnDemandSequenceInput = {
 };
 export type CreateOnDemandCampaignInput = {
     name: string;
-    clientProspectId: string;
+    clientProspectId?: string;
+    senderLinkedinUrl?: string;
     senderIds: string[];
     campaignBrief?: unknown;
     offerPositioning?: Record<string, unknown>;
@@ -54,6 +56,10 @@ export declare const onDemandToolDefinitions: ({
                 type: string;
                 description: string;
             };
+            senderLinkedinUrl: {
+                type: string;
+                description: string;
+            };
             offerPositioning: {
                 type: string;
                 description: string;
@@ -84,6 +90,10 @@ export declare const onDemandToolDefinitions: ({
                 type: string;
                 description: string;
             };
+            senderLinkedinUrl: {
+                type: string;
+                description: string;
+            };
             senderIds: {
                 type: string;
                 items: {
@@ -155,6 +165,7 @@ export declare const onDemandToolDefinitions: ({
             name?: undefined;
             senderIds?: undefined;
             clientProspectId?: undefined;
+            senderLinkedinUrl?: undefined;
             offerPositioning?: undefined;
             campaignBrief?: undefined;
             sequenceTemplate?: undefined;
@@ -176,6 +187,7 @@ export declare const onDemandToolDefinitions: ({
             name?: undefined;
             senderIds?: undefined;
             clientProspectId?: undefined;
+            senderLinkedinUrl?: undefined;
             offerPositioning?: undefined;
             campaignBrief?: undefined;
             sequenceTemplate?: undefined;
@@ -207,6 +219,7 @@ export declare const onDemandToolDefinitions: ({
             name?: undefined;
             senderIds?: undefined;
             clientProspectId?: undefined;
+            senderLinkedinUrl?: undefined;
             offerPositioning?: undefined;
             campaignBrief?: undefined;
             sequenceTemplate?: undefined;

package/dist/tools/one-off.js

@@ -38,7 +38,8 @@ const SIMPLE_LINEAR_TEMPLATE = {
 export const onDemandToolDefinitions = [
     {
         name: "create_on_demand_table",
-        description: "Create an on-demand campaign table backed by a lightweight CampaignOffer. Returns tableId + campaignOfferId.",
+        description: "Create an on-demand campaign table backed by a lightweight CampaignOffer. Returns tableId + campaignOfferId.\n\n" +
+            "INPUTS: Pass EITHER clientProspectId (existing prospect ID) OR senderLinkedinUrl (sender's LinkedIn profile URL). One is required.",
         inputSchema: {
             type: "object",
             properties: {
@@ -53,7 +54,11 @@ export const onDemandToolDefinitions = [
                 },
                 clientProspectId: {
                     type: "string",
-                    description: "Client prospect ID for CampaignOffer (use enrich_sender to obtain it)",
+                    description: "Optional. Pass this OR senderLinkedinUrl.",
+                },
+                senderLinkedinUrl: {
+                    type: "string",
+                    description: "Optional. Sender's LinkedIn profile URL — used to lazy-resolve the prospect at send-time when clientProspectId is not yet available.",
                 },
                 offerPositioning: {
                     type: "object",
@@ -63,12 +68,13 @@ export const onDemandToolDefinitions = [
                     description: "Optional campaign brief content (markdown or JSON)",
                 },
             },
-            required: ["name", "clientProspectId"],
+            required: ["name"],
         },
     },
     {
         name: "create_on_demand_campaign",
-        description: "Create a lightweight CampaignOffer + workflow table, set senders, and initialize sequence columns. Auto-selects template by sender tiers unless provided.",
+        description: "Create a lightweight CampaignOffer + workflow table, set senders, and initialize sequence columns. Auto-selects template by sender tiers unless provided.\n\n" +
+            "INPUTS: Pass EITHER clientProspectId (existing prospect ID) OR senderLinkedinUrl (sender's LinkedIn profile URL). One is required.",
         inputSchema: {
             type: "object",
             properties: {
@@ -78,7 +84,11 @@ export const onDemandToolDefinitions = [
                 },
                 clientProspectId: {
                     type: "string",
-                    description: "Client prospect ID from enrich_sender",
+                    description: "Optional. Pass this OR senderLinkedinUrl.",
+                },
+                senderLinkedinUrl: {
+                    type: "string",
+                    description: "Optional. Sender's LinkedIn profile URL — used to lazy-resolve the prospect at send-time when clientProspectId is not yet available.",
                 },
                 senderIds: {
                     type: "array",
@@ -101,7 +111,7 @@ export const onDemandToolDefinitions = [
                     description: "Set true to overwrite existing sequence columns",
                 },
             },
-            required: ["name", "clientProspectId", "senderIds"],
+            required: ["name", "senderIds"],
         },
     },
     {
@@ -180,6 +190,9 @@ export const onDemandToolDefinitions = [
     },
 ];
 export async function createOnDemandTable(input) {
+    if (!input.clientProspectId && !input.senderLinkedinUrl) {
+        throw new Error("VALIDATION_ERROR: create_on_demand_table requires either clientProspectId (existing prospect ID) or senderLinkedinUrl (sender's LinkedIn profile URL). Pass one.");
+    }
     const api = getApi();
     return api.post("/api/v3/on-demand-campaigns", input);
 }
@@ -221,6 +234,9 @@ async function initCampaignSequence(input) {
     return api.put(`/api/v3/campaigns/${input.campaignOfferId}/sequence`, payload);
 }
 export async function createOnDemandCampaign(input) {
+    if (!input.clientProspectId && !input.senderLinkedinUrl) {
+        throw new Error("VALIDATION_ERROR: create_on_demand_campaign requires either clientProspectId (existing prospect ID) or senderLinkedinUrl (sender's LinkedIn profile URL). Pass one.");
+    }
     if (!Array.isArray(input.senderIds) || input.senderIds.length === 0) {
         throw new Error("senderIds must be a non-empty array");
     }
@@ -228,6 +244,7 @@ export async function createOnDemandCampaign(input) {
         name: input.name,
         senderIds: input.senderIds,
         clientProspectId: input.clientProspectId,
+        senderLinkedinUrl: input.senderLinkedinUrl,
         offerPositioning: input.offerPositioning,
         campaignBrief: input.campaignBrief,
     });

package/dist/tools/prompts.d.ts

@@ -41,7 +41,7 @@ export interface SearchSubskillPromptsResponse {
     }>;
 }
 export interface CompleteSenderResearchInput {
-    depth?: "minimal-verification" | "deep-proof";
+    depth?: "minimal-verification" | "deep-proof" | "parallel-batch";
     proofItemsFound?: number;
     caseStudyItemsFound?: number;
     credibilitySignalsFound?: number;
@@ -213,7 +213,7 @@ export declare function listSubskillPrompts(limit?: number, includePublic?: bool
 export declare function getSubskillPrompt(subskillName: string, offset?: number, limit?: number): SubskillPromptResponse;
 export declare function completeSenderResearch(input?: CompleteSenderResearchInput): {
     readonly completedAt: string;
-    readonly depth: "minimal-verification" | "deep-proof";
+    readonly depth: "minimal-verification" | "deep-proof" | "parallel-batch";
     readonly proofItemsFound: number;
     readonly caseStudyItemsFound: number;
     readonly credibilitySignalsFound: number;