@sellable/mcp 0.1.553 → 0.1.555

package/dist/tools/registry.d.ts

@@ -662,6 +662,18 @@ export declare const allTools: ({
                 enum: string[];
                 description: string;
             };
+            targetDate: {
+                type: string;
+                description: string;
+            };
+            refillLaneKey: {
+                type: string;
+                description: string;
+            };
+            sourceEpoch: {
+                type: string;
+                description: string;
+            };
             disableLowPassRateStop: {
                 type: string;
                 description: string;
@@ -671,6 +683,7 @@ export declare const allTools: ({
                 description: string;
             };
             jobId?: undefined;
+            expectedUpdatedAt?: undefined;
         };
         required: string[];
         additionalProperties: boolean;
@@ -705,11 +718,52 @@ export declare const allTools: ({
             autoContinue?: undefined;
             senderId?: undefined;
             actionType?: undefined;
+            targetDate?: undefined;
+            refillLaneKey?: undefined;
+            sourceEpoch?: undefined;
             disableLowPassRateStop?: undefined;
+            expectedUpdatedAt?: undefined;
         };
         additionalProperties: boolean;
         required?: undefined;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            jobId: {
+                type: string;
+            };
+            expectedUpdatedAt: {
+                type: string;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description?: undefined;
+            };
+            campaignId?: undefined;
+            tableId?: undefined;
+            targetPreparedMessages?: undefined;
+            maxRowsToCheck?: undefined;
+            batchSize?: undefined;
+            maxBatchRows?: undefined;
+            approvalMode?: undefined;
+            rowSelector?: undefined;
+            excludeRowIds?: undefined;
+            autoContinue?: undefined;
+            senderId?: undefined;
+            actionType?: undefined;
+            targetDate?: undefined;
+            refillLaneKey?: undefined;
+            sourceEpoch?: undefined;
+            disableLowPassRateStop?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -7554,47 +7608,54 @@ export declare const allTools: ({
                 type: string;
                 description: string;
             };
-        };
-        required: string[];
-        additionalProperties: boolean;
-    };
-} | {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: string;
-        properties: {
-            workspaceId: {
-                type: string;
-                description: string;
-            };
-            runId: {
+            expectedTargets: {
                 type: string;
-                description: string;
-            };
-            fence: {
-                type: string;
-                description: string;
+                maxItems: 25;
+                items: {
+                    type: string;
+                    properties: {
+                        campaignId: {
+                            type: string;
+                        };
+                        tableId: {
+                            type: string;
+                        };
+                        refillLaneKey: {
+                            type: string;
+                        };
+                        branchActionTypes: {
+                            type: string;
+                            minItems: number;
+                            uniqueItems: boolean;
+                            items: {
+                                type: string;
+                                enum: string[];
+                            };
+                        };
+                        senderIds: {
+                            type: string;
+                            minItems: number;
+                            maxItems: 100;
+                            uniqueItems: boolean;
+                            items: {
+                                type: string;
+                            };
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                };
             };
-            dryRun: {
+            expectedTargetsHash: {
                 type: string;
                 description: string;
             };
-            approvalMode: {
+            maxPlacements: {
                 type: string;
-                enum: string[];
+                minimum: number;
+                maximum: 150;
                 description: string;
             };
-            senderIds: {
-                type: string;
-                items: {
-                    type: string;
-                };
-            };
-            intent: {
-                type: string;
-                enum: string[];
-            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/registry.js

@@ -34,10 +34,9 @@ import { onDemandToolDefinitions } from "./one-off.js";
 import { processingToolDefinitions } from "./processing.js";
 import { promptToolDefinitions } from "./prompts.js";
 import { readinessToolDefinitions } from "./readiness.js";
-import { refreshSenderEngagementToolDefinitions } from "./refresh-sender-engagement.js";
-import { refillSendsV2ToolDefinitions } from "./refill-sends-v2.js";
 import { refillSendsToolDefinitions } from "./refill-sends.js";
 import { refillTargetPlanToolDefinitions } from "./refill-target-plan.js";
+import { refreshSenderEngagementToolDefinitions } from "./refresh-sender-engagement.js";
 import { rowToolDefinitions } from "./rows.js";
 import { rubricToolDefinitions } from "./rubrics.js";
 import { schedulerFillCapacityToolDefinitions } from "./scheduler-fill-capacity.js";
@@ -61,7 +60,6 @@ export const allTools = [
     ...schedulerFillCapacityToolDefinitions,
     ...schedulerRunToolDefinitions,
     ...refillSendsToolDefinitions,
-    ...refillSendsV2ToolDefinitions,
     ...setupEvergreenCampaignsToolDefinitions,
     ...campaignHorizonFillToolDefinitions,
     ...campaignMessagePreparationToolDefinitions,

package/dist/tools/scheduler-run.d.ts

@@ -1,10 +1,23 @@
 type SchedulerRunAction = "run" | "status";
+export declare const REFILL_SCHEDULER_EXPECTED_TARGET_LIMIT: 25;
+export declare const REFILL_SCHEDULER_EXPECTED_TARGET_SENDER_LIMIT: 100;
+export declare const REFILL_SCHEDULER_MAX_PLACEMENTS: 150;
+export type SchedulerExpectedTargetInput = {
+    campaignId: string;
+    tableId: string;
+    refillLaneKey: string;
+    branchActionTypes: Array<"send_invite" | "send_inmail_open" | "send_inmail_closed">;
+    senderIds: string[];
+};
 type RunSchedulerSweepInput = {
     workspaceId: string;
     action?: SchedulerRunAction;
     targetDate?: string;
     requestKey?: string;
     targetShapeRevision?: string;
+    expectedTargets?: SchedulerExpectedTargetInput[];
+    expectedTargetsHash?: string;
+    maxPlacements?: number;
 };
 export declare const schedulerRunToolDefinitions: {
     name: string;
@@ -33,6 +46,54 @@ export declare const schedulerRunToolDefinitions: {
                 type: string;
                 description: string;
             };
+            expectedTargets: {
+                type: string;
+                maxItems: 25;
+                items: {
+                    type: string;
+                    properties: {
+                        campaignId: {
+                            type: string;
+                        };
+                        tableId: {
+                            type: string;
+                        };
+                        refillLaneKey: {
+                            type: string;
+                        };
+                        branchActionTypes: {
+                            type: string;
+                            minItems: number;
+                            uniqueItems: boolean;
+                            items: {
+                                type: string;
+                                enum: string[];
+                            };
+                        };
+                        senderIds: {
+                            type: string;
+                            minItems: number;
+                            maxItems: 100;
+                            uniqueItems: boolean;
+                            items: {
+                                type: string;
+                            };
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                };
+            };
+            expectedTargetsHash: {
+                type: string;
+                description: string;
+            };
+            maxPlacements: {
+                type: string;
+                minimum: number;
+                maximum: 150;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/scheduler-run.js

@@ -1,5 +1,9 @@
+import { createHash } from "crypto";
 import { getApi } from "../api.js";
 import { normalizeExplicitWorkspaceId, workspaceRequestOptions, } from "./workspace-context.js";
+export const REFILL_SCHEDULER_EXPECTED_TARGET_LIMIT = 25;
+export const REFILL_SCHEDULER_EXPECTED_TARGET_SENDER_LIMIT = 100;
+export const REFILL_SCHEDULER_MAX_PLACEMENTS = 150;
 async function postSchedulerRun(body, workspaceId) {
     const api = getApi();
     const requestOptions = workspaceRequestOptions(workspaceId);
@@ -29,10 +33,89 @@ function normalizeOptionalScopeValue(value, field) {
     }
     return value.trim();
 }
+function canonicalizeExpectedTargets(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error("expectedTargets must be a non-empty array.");
+    }
+    if (value.length > REFILL_SCHEDULER_EXPECTED_TARGET_LIMIT) {
+        throw new Error(`expected_target_overflow: expectedTargets exceeds ${REFILL_SCHEDULER_EXPECTED_TARGET_LIMIT}.`);
+    }
+    const supportedActions = new Set([
+        "send_invite",
+        "send_inmail_open",
+        "send_inmail_closed",
+    ]);
+    const canonical = value.map((rawTarget, index) => {
+        if (!rawTarget ||
+            typeof rawTarget !== "object" ||
+            Array.isArray(rawTarget)) {
+            throw new Error(`expectedTargets[${index}] must be an object.`);
+        }
+        const target = rawTarget;
+        const allowedKeys = new Set([
+            "campaignId",
+            "tableId",
+            "refillLaneKey",
+            "branchActionTypes",
+            "senderIds",
+        ]);
+        if (Object.keys(target).some((key) => !allowedKeys.has(key))) {
+            throw new Error(`expectedTargets[${index}] contains unsupported fields.`);
+        }
+        const campaignId = normalizeOptionalScopeValue(target.campaignId, `expectedTargets[${index}].campaignId`);
+        const tableId = normalizeOptionalScopeValue(target.tableId, `expectedTargets[${index}].tableId`);
+        const refillLaneKey = normalizeOptionalScopeValue(target.refillLaneKey, `expectedTargets[${index}].refillLaneKey`);
+        if (!campaignId ||
+            !tableId ||
+            !refillLaneKey ||
+            !Array.isArray(target.branchActionTypes) ||
+            target.branchActionTypes.length === 0 ||
+            !Array.isArray(target.senderIds) ||
+            target.senderIds.length === 0) {
+            throw new Error(`expectedTargets[${index}] is incomplete.`);
+        }
+        if (target.senderIds.length > REFILL_SCHEDULER_EXPECTED_TARGET_SENDER_LIMIT) {
+            throw new Error(`expected_target_overflow: expectedTargets[${index}].senderIds exceeds ${REFILL_SCHEDULER_EXPECTED_TARGET_SENDER_LIMIT}.`);
+        }
+        const branchActionTypes = target.branchActionTypes.map((actionType) => {
+            if (typeof actionType !== "string" || !supportedActions.has(actionType)) {
+                throw new Error(`expectedTargets[${index}] contains an unsupported branch action.`);
+            }
+            return actionType;
+        });
+        const senderIds = target.senderIds.map((senderId) => {
+            const normalized = normalizeOptionalScopeValue(senderId, `expectedTargets[${index}].senderIds`);
+            if (!normalized) {
+                throw new Error(`expectedTargets[${index}].senderIds must be non-empty.`);
+            }
+            return normalized;
+        });
+        if (new Set(branchActionTypes).size !== branchActionTypes.length ||
+            new Set(senderIds).size !== senderIds.length) {
+            throw new Error(`expectedTargets[${index}] branchActionTypes and senderIds must be unique.`);
+        }
+        return {
+            campaignId,
+            tableId,
+            refillLaneKey,
+            branchActionTypes: branchActionTypes.sort(),
+            senderIds: senderIds.sort(),
+        };
+    });
+    canonical.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    const targetKeys = canonical.map((target) => JSON.stringify(target));
+    if (new Set(targetKeys).size !== targetKeys.length) {
+        throw new Error("expectedTargets contains duplicate canonical targets.");
+    }
+    return canonical;
+}
+function computeExpectedTargetsHash(targets) {
+    return createHash("sha256").update(JSON.stringify(targets)).digest("hex");
+}
 export const schedulerRunToolDefinitions = [
     {
         name: "run_scheduler_sweep",
-        description: 'Trigger the product scheduler placement sweep for one explicit workspace now, or read the last on-demand scheduler run status with action "status". A run is workspace-wide, not a scoped run for one campaign/table, and returns a synchronous envelope with status ran, attached, backoff, window_closed_noop, or failed; retryAfterMs for backoff replays; and a backward-compatible receipt. In v2 receipts, readyCellsFound is total scheduler-ready supply found before filters, cellsConsidered is the allocation-attempt count that survived prefilters, prefiltered means ready cells removed before allocation such as no capacity, stale paid InMail credit facts, or sender mismatch, skipped means considered cells rejected by hard scheduler gates, and deferred means considered cells waiting on windows/capacity/cooldown. campaignScopeSummary lists bounded tables/campaigns the workspace-wide run inspected; absence there is not a scoped-run guarantee that the target was ready. The receipt can include readyCellsByType, consideredCellsByType, prefilterReasons, skippedReasons, deferredReasons, summary, and nextAction. It places cells within existing scheduler gates only: it can move placement earlier, but it cannot bypass sending windows, daily limits, cooldowns, sender gates, billing, or credit thresholds, and it never sends messages directly. Repeated calls inside the backoff window replay the last receipt verbatim. Status is read-only and scoped to the last on-demand run only; cron sweeps are not recorded here.',
+        description: 'Trigger the product scheduler placement sweep for one explicit workspace now, or read the last on-demand scheduler run status with action "status". A run is workspace-wide, not a scoped run for one campaign/table, and returns a synchronous envelope with status ran, attached, backoff, window_closed_noop, or failed; retryAfterMs for backoff replays; and a backward-compatible receipt. In v3 receipts, readyCellsFound is total scheduler-ready supply found before filters, cellsConsidered is the allocation-attempt count that survived prefilters, prefiltered means ready cells removed before allocation such as no capacity, stale paid InMail credit facts, or sender mismatch, skipped means considered cells rejected by hard scheduler gates, and deferred means considered cells waiting on windows/capacity/cooldown. campaignScopeSummary remains bounded display evidence, while expectedTargetSummary explains every hash-bound planner target exactly once without filtering placement. Expected targets require a frozen numeric total placement cap; unrelated eligible campaigns may consume that cap through normal workspace-wide gates, and changedCounts audits every actual placement by campaign, table, action, and sender. The receipt can include readyCellsByType, consideredCellsByType, prefilterReasons, skippedReasons, deferredReasons, summary, and nextAction. It places cells within existing scheduler gates only: it can move placement earlier, but it cannot bypass sending windows, daily limits, cooldowns, sender gates, billing, or credit thresholds, and it never sends messages directly. Repeated calls inside the backoff window replay the last receipt verbatim. Status is read-only and scoped to the last on-demand run only; cron sweeps are not recorded here.',
         inputSchema: {
             type: "object",
             properties: {
@@ -57,6 +140,56 @@ export const schedulerRunToolDefinitions = [
                     type: "string",
                     description: "Optional stable approved refill target-shape revision associated with requestKey.",
                 },
+                expectedTargets: {
+                    type: "array",
+                    maxItems: REFILL_SCHEDULER_EXPECTED_TARGET_LIMIT,
+                    items: {
+                        type: "object",
+                        properties: {
+                            campaignId: { type: "string" },
+                            tableId: { type: "string" },
+                            refillLaneKey: { type: "string" },
+                            branchActionTypes: {
+                                type: "array",
+                                minItems: 1,
+                                uniqueItems: true,
+                                items: {
+                                    type: "string",
+                                    enum: [
+                                        "send_invite",
+                                        "send_inmail_open",
+                                        "send_inmail_closed",
+                                    ],
+                                },
+                            },
+                            senderIds: {
+                                type: "array",
+                                minItems: 1,
+                                maxItems: REFILL_SCHEDULER_EXPECTED_TARGET_SENDER_LIMIT,
+                                uniqueItems: true,
+                                items: { type: "string" },
+                            },
+                        },
+                        required: [
+                            "campaignId",
+                            "tableId",
+                            "refillLaneKey",
+                            "branchActionTypes",
+                            "senderIds",
+                        ],
+                        additionalProperties: false,
+                    },
+                },
+                expectedTargetsHash: {
+                    type: "string",
+                    description: "Required SHA-256 of canonical expectedTargets for a target-aware run.",
+                },
+                maxPlacements: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: REFILL_SCHEDULER_MAX_PLACEMENTS,
+                    description: "Required frozen numeric total placement cap across the workspace-wide sweep when expectedTargets are present.",
+                },
             },
             required: ["workspaceId"],
             additionalProperties: false,
@@ -75,11 +208,60 @@ export async function runSchedulerSweep(input) {
     if (action !== "run" && action !== "status") {
         throw new Error('action must be "run" or "status" for run_scheduler_sweep.');
     }
+    const hasExpectedTargets = input.expectedTargets !== undefined;
+    const hasExpectedTargetScope = input.expectedTargetsHash !== undefined ||
+        input.maxPlacements !== undefined;
+    if (action === "status" && hasExpectedTargets) {
+        throw new Error("expectedTargets are only valid for action run.");
+    }
+    let expectedTargetRequest;
+    if (action === "run" && (hasExpectedTargets || hasExpectedTargetScope)) {
+        const expectedTargets = canonicalizeExpectedTargets(input.expectedTargets);
+        const expectedTargetsHash = normalizeOptionalScopeValue(input.expectedTargetsHash, "expectedTargetsHash");
+        if (!expectedTargetsHash ||
+            expectedTargetsHash !== computeExpectedTargetsHash(expectedTargets)) {
+            throw new Error("expectedTargetsHash must match the canonical expectedTargets payload.");
+        }
+        if (typeof input.maxPlacements !== "number" ||
+            !Number.isInteger(input.maxPlacements) ||
+            input.maxPlacements <= 0 ||
+            input.maxPlacements > REFILL_SCHEDULER_MAX_PLACEMENTS) {
+            throw new Error(`maxPlacements must be an integer from 1 to ${REFILL_SCHEDULER_MAX_PLACEMENTS}.`);
+        }
+        if (!targetDate || !requestKey || !targetShapeRevision) {
+            throw new Error("expectedTargets require targetDate, requestKey, and targetShapeRevision.");
+        }
+        expectedTargetRequest = {
+            expectedTargets,
+            expectedTargetsHash,
+            maxPlacements: input.maxPlacements,
+        };
+    }
+    let expectedStatusScope;
+    if (action === "status" && hasExpectedTargetScope) {
+        const expectedTargetsHash = normalizeOptionalScopeValue(input.expectedTargetsHash, "expectedTargetsHash");
+        if (!expectedTargetsHash ||
+            typeof input.maxPlacements !== "number" ||
+            !Number.isInteger(input.maxPlacements) ||
+            input.maxPlacements <= 0 ||
+            input.maxPlacements > REFILL_SCHEDULER_MAX_PLACEMENTS ||
+            !targetDate ||
+            !requestKey ||
+            !targetShapeRevision) {
+            throw new Error("hash-bound status requires expectedTargetsHash, maxPlacements, targetDate, requestKey, and targetShapeRevision.");
+        }
+        expectedStatusScope = {
+            expectedTargetsHash,
+            maxPlacements: input.maxPlacements,
+        };
+    }
     return postSchedulerRun({
         workspaceId,
         action,
         ...(targetDate ? { targetDate } : {}),
         ...(requestKey ? { requestKey } : {}),
         ...(targetShapeRevision ? { targetShapeRevision } : {}),
+        ...(expectedTargetRequest ?? {}),
+        ...(expectedStatusScope ?? {}),
     }, workspaceId);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.553",
+  "version": "0.1.555",
   "type": "module",
   "description": "Sellable MCP server for Claude Code, Codex, and Hermes campaign workflows",
   "main": "dist/index.js",