@sellable/mcp 0.1.336 → 0.1.338

package/README.md

@@ -96,8 +96,17 @@ startup/auth update check and tells the agent to run
 `curl -fsSL "https://app.sellable.dev/api/v2/cli/install" | sh` when the
 installed runtime is behind npm.
 
-For CI/scripted installs, set `SELLABLE_TOKEN` and `SELLABLE_WORKSPACE_ID`
-before running the curl installer. The public path remains:
+First-run login is the normal auth path. Install Sellable, launch a workflow in
+Claude Code or Codex, and let the agent complete the browser magic-link login.
+If the browser login page shows a manual fallback, paste:
+
+```bash
+sellable auth set <token> --workspace-id <workspace_id>
+```
+
+For CI/env-only scripted installs, operators can set `SELLABLE_TOKEN` and
+`SELLABLE_WORKSPACE_ID` before running the curl installer. The public path
+remains:
 
 ```bash
 curl -fsSL "https://app.sellable.dev/api/v2/cli/install" | sh
@@ -117,11 +126,17 @@ and publishes with a temporary npm config file. Prefer `NPM_TOKEN=<npm token>` i
 `prod.env`; `NODE_AUTH_TOKEN`, `SELLABLE_NPM_TOKEN`, and `NPM_PUBLISH_TOKEN` are
 also supported.
 
-### 2. Generate API Token
+### 2. First-Run Login
 
-1. Go to https://app.sellable.dev/settings
-2. Click "Generate Token"
-3. Copy the token (starts with `skt_live_`)
+Launch a Sellable workflow after install. The agent will start first-run login,
+send the magic link, wait for browser confirmation, and write canonical auth to
+`~/.sellable/config.json`.
+
+If the browser confirmation page shows a scripted fallback, paste:
+
+```bash
+sellable auth set <token> --workspace-id <workspace_id>
+```
 
 ### 3. Claude Setup Fallback
 
@@ -135,17 +150,9 @@ Install MCP server manually:
 claude mcp add --transport stdio sellable -- npm exec --yes --package @sellable/mcp@latest -- sellable-mcp
 ```
 
-Create auth config at `~/.sellable/config.json`:
-
-```json
-{
-  "token": "skt_live_your_token_here",
-  "activeWorkspaceId": "your_workspace_id"
-}
-```
-
-The token is provided when you generate it. Use `list_workspaces` +
-`set_active_workspace` to choose a workspace if you don't know the ID yet.
+Do not hand-edit auth JSON for normal setup. Use first-run login or the
+`sellable auth set <token> --workspace-id <workspace_id>` fallback so the
+canonical config shape stays consistent.
 
 ### 4. Codex Setup
 
@@ -524,13 +531,21 @@ generation is not part of these inbox tools.
 
 ### "Sellable not configured" Error
 
-Create `~/.sellable/config.json` with your token. Get one at https://app.sellable.dev/settings?tab=integrations.
+Run a Sellable workflow to start first-run login. If the browser login page
+shows a manual fallback, paste:
+
+```bash
+sellable auth set <token> --workspace-id <workspace_id>
+```
 
 ### Token Not Working
 
 1. Make sure token starts with `skt_`
 2. Check token is not revoked
-3. Verify activeWorkspaceId matches your workspace (or run list_workspaces + set_active_workspace)
+3. If the token came from an older Settings flow and returns 403 on campaign or
+   enrichment writes, regenerate through first-run login or the scripted
+   fallback command above
+4. Verify activeWorkspaceId matches your workspace (or run list_workspaces + set_active_workspace)
 
 ## Support
 

package/dist/api.js

@@ -19,9 +19,11 @@ export class SellableApi {
         const missingWorkspace = status === 400 && errorText.includes("Workspace");
         const guidance = isAuthError
             ? "Sellable authentication failed.\n\n" +
-                `Update ${getConfigPath()} with a valid token from Sellable Settings -> Integrations, then retry.\n\n` +
-                "NOTE: If the token was just updated via the LLM (editing the config file), " +
-                "the change should take effect immediately. If it still fails, restart Claude Code to restart the MCP server."
+                "Run the first-run Sellable login flow from a Sellable workflow, then retry.\n\n" +
+                "If the browser login page shows a manual fallback command, use:\n" +
+                "sellable auth set <token> --workspace-id <workspace_id>\n\n" +
+                `Current config path: ${getConfigPath()}\n\n` +
+                "Older copied Settings tokens can be stale, restricted, or missing write/credit permissions. Sign in again so Sellable mints the current agent token."
             : missingWorkspace
                 ? "No active workspace selected.\n\n" +
                     "Run list_workspaces then set_active_workspace to choose a workspace."

package/dist/auth.js

@@ -48,6 +48,16 @@ export function getConfigPath() {
     }
     return candidates[0];
 }
+function getConfigWritePath() {
+    const explicitConfigPath = process.env.SELLABLE_CONFIG_PATH?.trim();
+    if (explicitConfigPath) {
+        return path.resolve(explicitConfigPath);
+    }
+    if (configFileName === "sellable.json") {
+        return path.join(os.homedir(), ".sellable", "config.json");
+    }
+    return getConfigPath();
+}
 function normalizeConfig(raw) {
     return {
         ...raw,
@@ -66,14 +76,12 @@ export function getConfig() {
     const configPath = getConfigPath();
     if (!fs.existsSync(configPath)) {
         throw new Error("Sellable not configured.\n\n" +
-            `Create ${configPath} with your token:\n` +
-            "{\n" +
-            '  "token": "skt_live_..."\n' +
-            "}\n\n" +
+            "Run a Sellable workflow to start first-run login, for example /sellable:create-campaign in Claude Code or $sellable:create-campaign in Codex.\n\n" +
+            "If the browser login page shows a manual fallback command, paste it in your terminal:\n" +
+            "sellable auth set <token> --workspace-id <workspace_id>\n\n" +
+            `Preferred config path: ${getConfigWritePath()}\n\n` +
             "Config path resolution order:\n" +
-            `${renderConfigPathOrder(configPathCandidates)}\n\n` +
-            "Get your token at: https://app.sellable.dev/settings?tab=integrations\n" +
-            "Then run list_workspaces + set_active_workspace to select a workspace.");
+            `${renderConfigPathOrder(configPathCandidates)}`);
     }
     try {
         const content = fs.readFileSync(configPath, "utf-8");
@@ -118,7 +126,8 @@ export function updateActiveWorkspace(params) {
         fs.mkdirSync(configDir, { recursive: true });
     }
     if (!fs.existsSync(configPath)) {
-        throw new Error(`Sellable not configured. Create ${configPath} with your token first.`);
+        throw new Error("Sellable not configured. Run a Sellable workflow to start first-run login, " +
+            "or paste the browser fallback command: sellable auth set <token> --workspace-id <workspace_id>.");
     }
     const content = fs.readFileSync(configPath, "utf-8");
     let raw;
@@ -158,7 +167,8 @@ export function updateActiveWorkspace(params) {
 function readRawConfigFile() {
     const configPath = getConfigPath();
     if (!fs.existsSync(configPath)) {
-        throw new Error(`Sellable not configured. Create ${configPath} with your token first.`);
+        throw new Error("Sellable not configured. Run a Sellable workflow to start first-run login, " +
+            "or paste the browser fallback command: sellable auth set <token> --workspace-id <workspace_id>.");
     }
     const content = fs.readFileSync(configPath, "utf-8");
     try {
@@ -197,15 +207,36 @@ function writeRawConfigFile(configPath, raw) {
  * new config without an MCP server restart.
  */
 export function writeNewConfig(opts) {
-    const configPath = getConfigPath();
-    const raw = {
+    const configPath = getConfigWritePath();
+    let raw = {};
+    if (fs.existsSync(configPath)) {
+        const content = fs.readFileSync(configPath, "utf-8");
+        try {
+            raw = JSON.parse(content);
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error(`Invalid JSON in ${configPath}: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    const authFields = {
         token: opts.token,
         activeWorkspaceId: opts.activeWorkspaceId,
         apiUrl: opts.apiUrl,
     };
-    if (opts.activeWorkspaceName) {
-        raw.activeWorkspaceName = opts.activeWorkspaceName;
+    if (opts.activeWorkspaceName)
+        authFields.activeWorkspaceName = opts.activeWorkspaceName;
+    const { envConfig, set } = getActiveEnvConfigRef(raw);
+    const nextEnvConfig = {
+        ...envConfig,
+        ...authFields,
+    };
+    if (!opts.activeWorkspaceName) {
+        delete nextEnvConfig.activeWorkspaceName;
     }
+    set(nextEnvConfig);
     writeRawConfigFile(configPath, raw);
     return { configPath };
 }

package/dist/server.js

@@ -6,7 +6,10 @@ import { getAuthStatus } from "./tools/auth.js";
 import { handleAddColumn, handleCommitBlueprint, } from "./tools/blueprint-commit.js";
 import { bootstrapCreateCampaign } from "./tools/bootstrap.js";
 import { prepareCampaignAbTest } from "./tools/campaign-ab-test.js";
+import { resolveCampaignFillRoute } from "./tools/campaign-fill-routing.js";
+import { fillCampaignHorizon } from "./tools/campaign-horizon-fill.js";
 import { cancelPrepareCampaignMessages, getPrepareCampaignMessagesStatus, startPrepareCampaignMessages, } from "./tools/campaign-message-preparation.js";
+import { getCampaignRefillState } from "./tools/campaign-refill-state.js";
 import { getCampaignTableSchema, queueCampaignCells, recordCampaignReviewBatch, reviseMessageTemplateAndRerun, selectCampaignCells, waitForCampaignProcessing, } from "./tools/campaign-processing.js";
 import { createCampaign, duplicateCampaign, getCampaign, getCampaignMessagesPreview, getCampaigns, pauseCampaign, startCampaign, updateCampaign, updateCampaignBrief, } from "./tools/campaigns.js";
 import { queueCells, updateCell } from "./tools/cells.js";
@@ -178,6 +181,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_campaign_messages_preview":
                 result = await getCampaignMessagesPreview(args);
                 break;
+            case "resolve_campaign_fill_route":
+                result = await resolveCampaignFillRoute(args);
+                break;
+            case "get_campaign_refill_state":
+                result = await getCampaignRefillState(args);
+                break;
+            case "fill_campaign_horizon":
+                result = await fillCampaignHorizon(args);
+                if (args?.campaignId) {
+                    markCampaignContextDirty(args.campaignId, "fill_campaign_horizon");
+                }
+                break;
             case "start_campaign_message_preparation":
             case "start_prepare_campaign_messages":
                 result = await startPrepareCampaignMessages(args);

package/dist/tools/campaign-fill-routing.d.ts

@@ -0,0 +1,39 @@
+type CampaignFillIntent = "plain" | "evergreen" | "active";
+type ResolveCampaignFillRouteInput = {
+    intent: CampaignFillIntent;
+    campaignId?: string;
+    tableId?: string;
+    limit?: number;
+};
+export declare const campaignFillRoutingToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            intent: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function resolveCampaignFillRoute(input: ResolveCampaignFillRouteInput): Promise<unknown>;
+export {};

package/dist/tools/campaign-fill-routing.js

@@ -0,0 +1,45 @@
+import { getApi } from "../api.js";
+async function postCampaignFillRoute(body) {
+    const api = getApi();
+    return api.post("/api/v3/mcp/campaign-fill-routing", body);
+}
+export const campaignFillRoutingToolDefinitions = [
+    {
+        name: "resolve_campaign_fill_route",
+        description: 'Audit-only resolver to call before interpreting plain "fill campaigns", "load everyone up", or similar fill requests. It decides whether the workspace has evergreen/horizon targets, currently active campaign-backed sequence targets, or no targets so the agent must ask what to create. It does not create, append, prepare, approve, schedule, launch, archive, delete, send, or call lower-level fill tools. Only call fill_campaign_horizon when this resolver returns route "evergreen_horizon" or the user explicitly requested evergreen/horizon and the returned target is eligible. Exact target narrowing uses campaignId or tableId only; never fuzzy campaign names.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                intent: {
+                    type: "string",
+                    enum: ["plain", "evergreen", "active"],
+                    description: 'Use "plain" for generic fill/load requests, "evergreen" for explicit evergreen/horizon fill, and "active" for explicit active campaign fill.',
+                },
+                campaignId: {
+                    type: "string",
+                    description: "Optional exact CampaignOffer.id to narrow routing. Do not pass campaign names.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional exact WorkflowTable.id to narrow routing. Do not pass table names.",
+                },
+                limit: {
+                    type: "number",
+                    minimum: 1,
+                    maximum: 100,
+                    description: "Maximum returned targets/skippedTargets.",
+                },
+            },
+            required: ["intent"],
+            additionalProperties: false,
+        },
+    },
+];
+export function resolveCampaignFillRoute(input) {
+    return postCampaignFillRoute({
+        intent: input.intent,
+        campaignId: input.campaignId,
+        tableId: input.tableId,
+        limit: input.limit,
+    });
+}

package/dist/tools/campaign-horizon-fill.d.ts

@@ -0,0 +1,93 @@
+type FillCampaignHorizonInput = {
+    action: "audit" | "apply";
+    campaignId: string;
+    tableId?: string;
+    stateRevision?: string;
+    excludedPostIds?: string[];
+    excludedPostUrls?: string[];
+    excludedAuthorProfileUrls?: string[];
+    excludedAuthorNames?: string[];
+    targetPreparedMessages?: number;
+    maxRowsToCheck?: number;
+    batchSize?: number;
+};
+export declare const campaignHorizonFillToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+            stateRevision: {
+                type: string;
+                description: string;
+            };
+            excludedPostIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                maxItems: number;
+                description: string;
+            };
+            excludedPostUrls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                maxItems: number;
+                description: string;
+            };
+            excludedAuthorProfileUrls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                maxItems: number;
+                description: string;
+            };
+            excludedAuthorNames: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                maxItems: number;
+                description: string;
+            };
+            targetPreparedMessages: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            maxRowsToCheck: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            batchSize: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function fillCampaignHorizon(input: FillCampaignHorizonInput): Promise<unknown>;
+export {};

package/dist/tools/campaign-horizon-fill.js

@@ -0,0 +1,92 @@
+import { getApi } from "../api.js";
+async function postHorizonFill(body) {
+    const api = getApi();
+    return api.post("/api/v3/mcp/campaign-horizon-fill", body);
+}
+export const campaignHorizonFillToolDefinitions = [
+    {
+        name: "fill_campaign_horizon",
+        description: "Evergreen/horizon-only tool: audit or apply a bounded CampaignOffer horizon fill from Signal Discovery/source lead-list rows only when resolve_campaign_fill_route returns route evergreen_horizon or the user explicitly requested evergreen/horizon and the target is managed-waterfall eligible. Use audit first to get stateRevision, then apply with that stateRevision. Apply imports at most 300 eligible non-excluded source rows, starts bounded message preparation in approval mode, skips rows from excluded posts/authors, and does not start or launch the campaign, send messages, or directly assign scheduler-owned send timestamps. Prepared/approved rows are intermediate only; report scheduled completion only after re-reading scheduler-owned scheduled cells with non-null scheduler timestamps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["audit", "apply"],
+                    description: 'Use "audit" to inspect counts/receipt without writes. Use "apply" with the audit stateRevision to import/prep.',
+                },
+                campaignId: {
+                    type: "string",
+                    description: "CampaignOffer.id for the campaign to fill.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional workflow table id. Must match the campaign workflowTableId when provided.",
+                },
+                stateRevision: {
+                    type: "string",
+                    description: "Required for apply. Copy from the immediately preceding audit receipt.",
+                },
+                excludedPostIds: {
+                    type: "array",
+                    items: { type: "string" },
+                    maxItems: 100,
+                    description: "Exact SignalSearchPost ids to exclude from import/preparation.",
+                },
+                excludedPostUrls: {
+                    type: "array",
+                    items: { type: "string" },
+                    maxItems: 100,
+                    description: "Exact LinkedIn post URLs to exclude from import/preparation.",
+                },
+                excludedAuthorProfileUrls: {
+                    type: "array",
+                    items: { type: "string" },
+                    maxItems: 100,
+                    description: "Exact LinkedIn author profile URLs whose source rows should be excluded.",
+                },
+                excludedAuthorNames: {
+                    type: "array",
+                    items: { type: "string" },
+                    maxItems: 25,
+                    description: "Exact author names to exclude only when they resolve unambiguously inside campaign Signal Discovery posts.",
+                },
+                targetPreparedMessages: {
+                    type: "number",
+                    minimum: 1,
+                    maximum: 300,
+                    description: "Prepared/approved message target for the first pass. Backend caps this at 300.",
+                },
+                maxRowsToCheck: {
+                    type: "number",
+                    minimum: 1,
+                    maximum: 300,
+                    description: "Hard first-pass row cap. Backend caps import and prep at 300 rows.",
+                },
+                batchSize: {
+                    type: "number",
+                    minimum: 1,
+                    maximum: 100,
+                    description: "Preparation batch size. Backend caps newly checked rows at 100 per batch.",
+                },
+            },
+            required: ["action", "campaignId"],
+            additionalProperties: false,
+        },
+    },
+];
+export function fillCampaignHorizon(input) {
+    return postHorizonFill({
+        action: input.action,
+        campaignId: input.campaignId,
+        tableId: input.tableId,
+        stateRevision: input.stateRevision,
+        excludedPostIds: input.excludedPostIds,
+        excludedPostUrls: input.excludedPostUrls,
+        excludedAuthorProfileUrls: input.excludedAuthorProfileUrls,
+        excludedAuthorNames: input.excludedAuthorNames,
+        targetPreparedMessages: input.targetPreparedMessages,
+        maxRowsToCheck: input.maxRowsToCheck,
+        batchSize: input.batchSize,
+    });
+}

package/dist/tools/campaign-message-preparation.d.ts

@@ -9,6 +9,7 @@ type StartPrepareMessagesInput = PrepareMessagesBaseInput & {
     targetPreparedMessages?: number;
     maxRowsToCheck?: number;
     batchSize?: number;
+    maxBatchRows?: number;
     approvalMode?: ApprovalMode;
     autoContinue?: boolean;
     disableLowPassRateStop?: boolean;
@@ -45,6 +46,12 @@ export declare const campaignMessagePreparationToolDefinitions: ({
                 maximum: number;
                 description: string;
             };
+            maxBatchRows: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
             approvalMode: {
                 type: string;
                 enum: string[];
@@ -81,6 +88,7 @@ export declare const campaignMessagePreparationToolDefinitions: ({
             targetPreparedMessages?: undefined;
             maxRowsToCheck?: undefined;
             batchSize?: undefined;
+            maxBatchRows?: undefined;
             approvalMode?: undefined;
             autoContinue?: undefined;
             disableLowPassRateStop?: undefined;

package/dist/tools/campaign-message-preparation.js

@@ -6,7 +6,7 @@ async function postPrepareMessages(body) {
 export const campaignMessagePreparationToolDefinitions = [
     {
         name: "start_campaign_message_preparation",
-        description: 'Start a bounded campaign message preparation job for a CampaignOffer campaignId. Use this after lead/message approval when the user asks to "fill up", "load", "prepare", or "schedule" sends for attached senders. It never launches the campaign. The job queues pending Enrich Prospect cells first, lets ICP/rubric and Generate Message cascade, then marks ready or approves only the bounded cohort. Omit maxRowsToCheck and batchSize for the adaptive default: calibrate on at least 100 actually-enriched rows, estimate the row budget from observed rubric/pass yield, cap rows at 2500, then use batches up to 250 once the sample is strong enough. Do not interpret checkedRows as enriched rows; use progress.enrichedRows, needsEnrichRows, activeCellCount, preparedMessages, and stopReason.',
+        description: 'Start a bounded message-preparation job for a specific existing CampaignOffer campaignId/tableId. This is the active_campaigns existing-row path after resolve_campaign_fill_route, exact target re-read, and active prep-job check; it is not campaign creation and not evergreen horizon fill. It never launches the campaign, sends messages, or directly writes scheduledFor. The job queues pending Enrich Prospect cells first, lets ICP/rubric and Generate Message cascade, then marks ready or approves only the bounded cohort. Prepared/approved/ready rows are intermediate only; scheduled completion requires a later re-read proving scheduler-owned scheduled cells with non-null scheduledFor. Surface active preparation jobs, exhausted source rows, disconnected Sales Nav/deleted sender accounts, missing sequence state, and other sender-health blockers separately from prepared/approved/scheduled counts. Omit maxRowsToCheck and batchSize for the adaptive default: calibrate on at least 100 actually-enriched rows, estimate the row budget from observed rubric/pass yield, cap rows at 300, and process at most 100 newly checked rows at a time. The worker will not pull another row batch while the current checked batch still has queueable or active cells. Do not interpret checkedRows as enriched rows; use progress.enrichedRows, needsEnrichRows, activeCellCount, preparedMessages, approvedMessages, and stopReason.',
         inputSchema: {
             type: "object",
             properties: {
@@ -19,19 +19,25 @@ export const campaignMessagePreparationToolDefinitions = [
                 maxRowsToCheck: {
                     type: "number",
                     minimum: 1,
-                    maximum: 2500,
-                    description: "Optional override capped by the backend at 2500. Omit this for adaptive sample-based row budgeting.",
+                    maximum: 300,
+                    description: "Optional override capped by the backend at 300. Omit this for adaptive sample-based row budgeting.",
                 },
                 batchSize: {
                     type: "number",
                     minimum: 1,
-                    maximum: 250,
-                    description: "Optional first-batch override capped by the backend at 250. Omit this to sample 100 rows before larger batches.",
+                    maximum: 100,
+                    description: "Optional first-batch override capped by the backend at 100. Omit this to sample 100 rows.",
+                },
+                maxBatchRows: {
+                    type: "number",
+                    minimum: 1,
+                    maximum: 100,
+                    description: "Optional max rows to add in any single preparation batch. Capped by the backend at 100.",
                 },
                 approvalMode: {
                     type: "string",
                     enum: ["mark_ready", "approve"],
-                    description: "Defaults to mark_ready. Use approve only when the user explicitly asks to flip Approved cells.",
+                    description: "Defaults to mark_ready. Use approve only when the user explicitly asks to flip Approved cells. Approval is not scheduling; it only makes the bounded cohort eligible for downstream scheduler ownership.",
                 },
                 autoContinue: { type: "boolean" },
                 disableLowPassRateStop: {
@@ -78,6 +84,7 @@ export function startPrepareCampaignMessages(input) {
         targetPreparedMessages: input.targetPreparedMessages,
         maxRowsToCheck: input.maxRowsToCheck,
         batchSize: input.batchSize,
+        maxBatchRows: input.maxBatchRows,
         approvalMode: input.approvalMode,
         autoContinue: input.autoContinue,
         disableLowPassRateStop: input.disableLowPassRateStop,

package/dist/tools/campaign-refill-state.d.ts

@@ -0,0 +1,25 @@
+type GetCampaignRefillStateInput = {
+    campaignId?: string;
+    tableId?: string;
+};
+export declare const campaignRefillStateToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function getCampaignRefillState(input: GetCampaignRefillStateInput): Promise<unknown>;
+export {};

package/dist/tools/campaign-refill-state.js

@@ -0,0 +1,32 @@
+import { getApi } from "../api.js";
+async function postCampaignRefillState(body) {
+    const api = getApi();
+    return api.post("/api/v3/mcp/campaign-refill-state", body);
+}
+export const campaignRefillStateToolDefinitions = [
+    {
+        name: "get_campaign_refill_state",
+        description: "read-only refill research primitive to call after resolve_campaign_fill_route and before any source import, message preparation, approval, scheduling, or horizon fill decision. It returns current campaign/table/source/sender/funnel/scheduler diagnostics plus freshness state for one exact campaignId or tableId only. This tool does not create rows, does not import leads, does not prepare messages, does not approve messages, does not schedule sends, does not launch campaigns, and does not expose direct campaign types as refillable targets. Exact targeting uses campaignId or tableId only; never pass campaign names or table names.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Optional exact CampaignOffer.id from resolve_campaign_fill_route. Do not pass campaign names.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional exact WorkflowTable.id from resolve_campaign_fill_route. Do not pass table names.",
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+];
+export function getCampaignRefillState(input) {
+    return postCampaignRefillState({
+        campaignId: input.campaignId,
+        tableId: input.tableId,
+    });
+}

package/dist/tools/campaigns.js

@@ -441,7 +441,7 @@ export const campaignToolDefinitions = [
     },
     {
         name: "start_campaign",
-        description: "Start a paused campaign, enabling the sweeper to send messages.",
+        description: "Start a paused campaign, enabling the sweeper to send messages. This is an explicit human launch/start action and must not be used as part of fill-send-horizon, message preparation, or scheduling-proof flows.",
         inputSchema: {
             type: "object",
             properties: {