@sellable/mcp 0.1.570 → 0.1.572

package/dist/tools/refill-sends-evergreen.js

@@ -0,0 +1,47 @@
+export const refillSendsEvergreenToolDefinitions = [
+    {
+        name: "refill_sends_evergreen",
+        description: "Read-only Phase 85 evergreen refill command contract. It performs no mutations and only tells the operator to call get_evergreen_refill_plan for a dry-run packet and journal.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Explicit request-scoped workspace id.",
+                },
+            },
+            required: ["workspaceId"],
+            additionalProperties: false,
+        },
+    },
+];
+export function refillSendsEvergreenCommand(input) {
+    return {
+        readOnly: true,
+        workspaceId: input.workspaceId ?? null,
+        firstOperationalSteps: [
+            "Call get_evergreen_refill_plan with the explicit workspaceId.",
+            "Read the returned packet, globalActionQueue, per-sender plans, and itinerary before taking any action.",
+            "Review the dry-run journal file path returned by get_evergreen_refill_plan.",
+            "Phase 85 is PLAN-ONLY; execution arrives in Phase 86.",
+        ],
+        approvalContract: "Nothing is approved or executable in Phase 85. The evergreen command is read-only; Phase 86 introduces execution approval.",
+        forbiddenActions: [
+            "Do not schedule sends.",
+            "Do not send messages.",
+            "Do not approve messages.",
+            "Do not prepare messages.",
+            "Do not start or launch campaigns.",
+            "Do not create campaigns.",
+            "Do not switch providers or source families.",
+            "Do not lower paid InMail thresholds.",
+            "Do not refresh paid InMail credits.",
+            "Do not write scheduler fields.",
+        ],
+        fillWindow: "Use only the target window and caps returned by get_evergreen_refill_plan.",
+        hostExamples: [
+            "refill_sends_evergreen({ workspaceId })",
+            "get_evergreen_refill_plan({ workspaceId })",
+        ],
+    };
+}

package/dist/tools/refill-sends.d.ts

@@ -418,6 +418,10 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
     workspaceResolution: string;
     intent: RefillSendsIntent;
 } | {
+    schedulerSweepDisclosure: {
+        workspaceWide: boolean;
+        reason: string | null;
+    } | null;
     targetPlan: unknown;
     targetPlanBeforePaidRefresh: unknown;
     targetPlanBeforeYoloPrimitive: unknown;

package/dist/tools/refill-sends.js

@@ -272,13 +272,13 @@ function buildRefillSendsCommand(input) {
                     : horizonSendDays === null
                         ? ""
                         : `, horizonSendDays: ${horizonSendDays}`}, approvalMode: "${approvalMode}" }) before any import, prep, approval, start, or schedule-affecting action.`,
-            "Render target.eligibleSenderLedger and target.senderRefillPlans before mutation. Preserve the coverage labels Need to prepare, Goal, Already sent, Scheduled, Ready and waiting to be scheduled, and Still need.",
+            "Render target.eligibleSenderLedger and target.senderRefillPlans before mutation. Preserve the coverage labels Need to prepare, Goal, Already sent, Scheduled, Ready and waiting to be scheduled, Still need to schedule, and Still need to prepare. Never render an unlabeled Still need value.",
             "Use target.globalActionQueue as the only cross-sender yolo queue: execute only target.globalActionQueue[0], one globally ranked primitive, then rerun get_refill_target_plan before choosing another action.",
             "When expectedTargetShapeRevision or expectedActionKey is supplied from an already rendered packet, compare both against the first fresh target plan before paid-credit refresh or any primitive. Return approval_scope_changed with the fresh packet on mismatch.",
             "Read target.senderRefillPlans[].refillReceipt as the public ladder receipt: it carries the selected campaign/sender/lane summary, skippedRungs, existingRowFrontier, and any absolute wait.deadlineAt. Do not choose source/copy/fallback work until that receipt proves the earlier ready/prep/approval rungs are exhausted.",
             "If get_refill_target_plan returns status complete, report eligible sender ledger, target.senderRefillPlans, gross target, selected days, sent count, scheduled count, projected count, campaign ids, targetShapeRevision, and no-op proof without asking for approval.",
             "Refill target lanes are connection invites (send_invite), standalone paid InMails (send_inmail_closed), or unified Sales Nav cascades represented publicly as send_inmail_closed with campaign classification sales_nav_cascade. For a Sales Nav cascade, refill the selected campaign first; its sequence can route prospects to Open InMail, paid InMail while fresh credits are >= 5, or same-campaign connection fallback without asking for separate open/paid/connection campaigns. Do not count send_dm as horizon target capacity.",
-            "If the exact-date global action is run_scheduler_sweep, execute it once and fully reread when remainingReadyOrProjectedGap is 0 but remainingProjectedGap is positive. Otherwise, run only a persistent read-only scheduler wait/reread loop; do not ask for prep/import/approval and do not close out while scheduler pickup is the only remaining state.",
+            "If the exact-date global action is run_scheduler_sweep, execute it once and fully reread when remainingReadyOrProjectedGap is 0 but remainingProjectedGap is positive. Otherwise, run only the receipt-scoped read-only scheduler wait/reread loop using its deadline and about-30-second reread metadata; stop at receipt_deadline, then unchanged_poll_bound, then run_budget. Never redispatch an active/uncertain request key, ask for prep/import/approval, or close out while scheduler pickup is the only remaining state.",
             `Resolve route with resolve_campaign_fill_route({ intent: "${intent}"${workspaceId ? `, workspaceId: "${workspaceId}"` : ""}${input.campaignId ? `, campaignId: "${input.campaignId}"` : ""}${input.tableId ? `, tableId: "${input.tableId}"` : ""} }).`,
             `If the plain route shows stale managed waterfall evidence, archived/completed shared slots, or targets that do not cover the selected sender set, immediately call resolve_campaign_fill_route({ intent: "active"${workspaceId ? `, workspaceId: "${workspaceId}"` : ""} }) and inspect current dashboard-active ACTIVE/PAUSED campaign-backed sequence campaigns before declaring a sender blocked.`,
             workspaceId
@@ -590,7 +590,17 @@ export async function executeRefillSendsCommand(input = {}) {
     const targetPlan = refreshActions.length > 0
         ? await getRefillTargetPlan(targetPlanInput)
         : targetPlanBeforePaidRefresh;
-    const selectedAction = yolo && refreshActions.length === 0 ? firstGlobalAction(targetPlan) : null;
+    const firstAction = firstGlobalAction(targetPlan);
+    const firstActionRecord = recordValue(firstAction);
+    const schedulerSweepDisclosure = firstActionRecord?.type === "run_scheduler_sweep" &&
+        firstActionRecord.workspaceWide === true &&
+        stringValue(firstActionRecord.reason)
+        ? {
+            workspaceWide: true,
+            reason: stringValue(firstActionRecord.reason),
+        }
+        : null;
+    const selectedAction = yolo && refreshActions.length === 0 ? firstAction : null;
     const primitiveAttempt = !yolo || refreshActions.length > 0
         ? null
         : await executeOneYoloPrimitive(selectedAction, workspaceId ?? undefined);
@@ -602,6 +612,7 @@ export async function executeRefillSendsCommand(input = {}) {
     const finalTargetPlan = postActionTargetPlan ?? targetPlan;
     return {
         ...command,
+        schedulerSweepDisclosure,
         targetPlan: finalTargetPlan,
         targetPlanBeforePaidRefresh: refreshActions.length > 0 ? targetPlanBeforePaidRefresh : null,
         targetPlanBeforeYoloPrimitive: yolo && refreshActions.length === 0 && postActionTargetPlan

package/dist/tools/refill-target-plan.js

@@ -1,4 +1,5 @@
 import { getApi } from "../api.js";
+import { REFILL_SCHEDULER_EXPECTED_TARGET_LIMIT, REFILL_SCHEDULER_EXPECTED_TARGET_SENDER_LIMIT, REFILL_SCHEDULER_MAX_PLACEMENTS, } from "./scheduler-run.js";
 import { normalizeExplicitWorkspaceId, workspaceRequestOptions, } from "./workspace-context.js";
 const REFILL_TARGET_ACTION_TYPES = [
     "send_invite",
@@ -88,7 +89,13 @@ const SCHEDULER_SWEEP_RECEIPT_GROUPS = [
     "campaignId",
     "tableId",
     "actionType",
+    "senderId",
 ];
+const SCHEDULER_EXPECTED_BRANCH_ACTION_TYPES = new Set([
+    "send_invite",
+    "send_inmail_open",
+    "send_inmail_closed",
+]);
 async function postRefillTargetPlan(body, workspaceId) {
     const api = getApi();
     const requestOptions = workspaceRequestOptions(workspaceId);
@@ -726,7 +733,12 @@ function paidInmailRefreshActionForSenderPlan(plan, paidInmail) {
         availableCredits: numberValue(paidInmail?.availableCredits),
         oldThreshold: numberValue(paidInmail?.threshold),
         maxStalenessSeconds: MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS,
-        actionKey: ["refresh_paid_inmail_credits", senderId, campaignId, columnId].join(":"),
+        actionKey: [
+            "refresh_paid_inmail_credits",
+            senderId,
+            campaignId,
+            columnId,
+        ].join(":"),
         rereadAfter: "get_refill_target_plan",
         reason: stringValue(paidInmail?.reason) ??
             "MCP paid InMail sender-credit facts require refresh.",
@@ -767,6 +779,34 @@ function sanitizeStructuredSenderPlans(value, selectedBySender) {
                 .map((action, index) => sanitizeStructuredAction(action, selectedBySender, "manual", index + 1))
                 .filter((action) => Boolean(action))
             : [];
+        const rawCoverage = isRecord(plan.coverage) ? plan.coverage : null;
+        const coverage = rawCoverage
+            ? (() => {
+                const goal = numberValue(rawCoverage.goal);
+                const alreadySent = numberValue(rawCoverage.alreadySent);
+                const scheduled = numberValue(rawCoverage.scheduled);
+                const readyAndWaitingToBeScheduled = numberValue(rawCoverage.readyAndWaitingToBeScheduled);
+                const stillNeedToSchedule = typeof rawCoverage.stillNeedToSchedule === "number"
+                    ? numberValue(rawCoverage.stillNeedToSchedule)
+                    : Math.max(0, goal - alreadySent - scheduled);
+                const stillNeedToPrepare = typeof rawCoverage.stillNeedToPrepare === "number"
+                    ? numberValue(rawCoverage.stillNeedToPrepare)
+                    : numberValue(rawCoverage.needToPrepare);
+                return {
+                    goal,
+                    alreadySent,
+                    scheduled,
+                    readyAndWaitingToBeScheduled,
+                    stillNeedToSchedule,
+                    stillNeedToPrepare,
+                    stillNeed: numberValue(rawCoverage.stillNeed),
+                    needToPrepare: numberValue(rawCoverage.needToPrepare),
+                    coveredTotal: typeof rawCoverage.coveredTotal === "number"
+                        ? rawCoverage.coveredTotal
+                        : undefined,
+                };
+            })()
+            : null;
         return {
             senderId: plan.senderId,
             senderName: stringValue(plan.senderName) ?? "",
@@ -790,20 +830,18 @@ function sanitizeStructuredSenderPlans(value, selectedBySender) {
                     schedulerCapacityMode: stringValue(plan.horizon.schedulerCapacityMode),
                 }
                 : {},
-            coverage: isRecord(plan.coverage)
-                ? {
-                    goal: numberValue(plan.coverage.goal),
-                    alreadySent: numberValue(plan.coverage.alreadySent),
-                    scheduled: numberValue(plan.coverage.scheduled),
-                    readyAndWaitingToBeScheduled: numberValue(plan.coverage.readyAndWaitingToBeScheduled),
-                    stillNeed: numberValue(plan.coverage.stillNeed),
-                    needToPrepare: numberValue(plan.coverage.needToPrepare),
-                    coveredTotal: typeof plan.coverage.coveredTotal === "number"
-                        ? plan.coverage.coveredTotal
-                        : undefined,
-                }
-                : {},
-            coverageDisplay: stringArray(plan.coverageDisplay),
+            coverage: coverage ?? {},
+            coverageDisplay: coverage
+                ? [
+                    `Need to prepare: ${coverage.stillNeedToPrepare} more rows`,
+                    `Goal: ${coverage.goal} sends`,
+                    `Already sent: ${coverage.alreadySent}`,
+                    `Scheduled: ${coverage.scheduled}`,
+                    `Ready and waiting to be scheduled: ${coverage.readyAndWaitingToBeScheduled}`,
+                    `Still need to schedule: ${coverage.stillNeedToSchedule}`,
+                    `Still need to prepare: ${coverage.stillNeedToPrepare}`,
+                ]
+                : [],
             campaignRanking: sanitizeCampaignRanking(plan.campaignRanking),
             paidInmail,
             sourcePlan: sanitizeSourcePlan(plan.sourcePlan),
@@ -848,15 +886,10 @@ function sanitizeSchedulerSweepSourceScopes(value) {
         const tableId = stringValue(entry.tableId)?.trim();
         const sourceLeadListId = stringValue(entry.sourceLeadListId)?.trim();
         const leadSourceProvider = stringValue(entry.leadSourceProvider)?.trim();
-        if (!campaignId ||
-            !tableId ||
-            !sourceLeadListId ||
-            !leadSourceProvider) {
+        if (!campaignId || !tableId || !sourceLeadListId || !leadSourceProvider) {
             return [];
         }
-        return [
-            { campaignId, tableId, sourceLeadListId, leadSourceProvider },
-        ];
+        return [{ campaignId, tableId, sourceLeadListId, leadSourceProvider }];
     });
     const unique = new Map(scopes.map((scope) => [
         [
@@ -874,20 +907,56 @@ function sanitizeSchedulerSweepSourceScopes(value) {
         return a.tableId.localeCompare(b.tableId);
     });
 }
+function sanitizeSchedulerExpectedTargets(value, scope) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > REFILL_SCHEDULER_EXPECTED_TARGET_LIMIT) {
+        return null;
+    }
+    const expectedTargets = [];
+    let senderCount = 0;
+    for (const rawTarget of value) {
+        if (!isRecord(rawTarget))
+            return null;
+        const campaignId = stringValue(rawTarget.campaignId)?.trim();
+        const tableId = stringValue(rawTarget.tableId)?.trim();
+        const refillLaneKey = allowedActionType(rawTarget.refillLaneKey);
+        const senderIds = sortedUniqueStrings(rawTarget.senderIds);
+        const branchActionTypes = sortedUniqueStrings(rawTarget.branchActionTypes).filter((actionType) => SCHEDULER_EXPECTED_BRANCH_ACTION_TYPES.has(actionType));
+        senderCount += senderIds.length;
+        if (!campaignId ||
+            !tableId ||
+            !refillLaneKey ||
+            senderIds.length === 0 ||
+            senderCount > REFILL_SCHEDULER_EXPECTED_TARGET_SENDER_LIMIT ||
+            branchActionTypes.length === 0 ||
+            !scope.campaignIds.includes(campaignId) ||
+            !scope.tableIds.includes(tableId) ||
+            senderIds.some((senderId) => !scope.senderIds.includes(senderId))) {
+            return null;
+        }
+        expectedTargets.push({
+            campaignId,
+            tableId,
+            refillLaneKey,
+            senderIds,
+            branchActionTypes,
+        });
+    }
+    return expectedTargets;
+}
 function sanitizeTargetSchedulerSweep(params) {
     if (!Array.isArray(params.value) ||
         !params.expectedWorkspaceId ||
         !params.expectedTargetDate ||
         !/^\d{4}-\d{2}-\d{2}$/.test(params.expectedTargetDate) ||
         !params.expectedTargetShapeRevision ||
-        !params.expectedStateRevision ||
-        params.remainingProjectedGap <= 0 ||
-        params.remainingReadyOrProjectedGap !== 0) {
+        !params.expectedStateRevision) {
         return null;
     }
-    const expectedSenderIds = [...params.selectedBySender.keys()].sort();
+    const expectedSenderIds = [...params.sweepEligibleBySender.keys()].sort();
     const expectedActionTypes = [
-        ...new Set(params.selectedBySender.values()),
+        ...new Set(params.sweepEligibleBySender.values()),
     ].sort();
     if (expectedSenderIds.length === 0 || expectedActionTypes.length === 0) {
         return null;
@@ -904,6 +973,9 @@ function sanitizeTargetSchedulerSweep(params) {
         const campaignIds = sortedUniqueStrings(input.campaignIds);
         const tableIds = sortedUniqueStrings(input.tableIds);
         const sourceScopes = sanitizeSchedulerSweepSourceScopes(input.sourceScopes);
+        const expectedTargets = sanitizeSchedulerExpectedTargets(input.expectedTargets, { senderIds, campaignIds, tableIds });
+        const expectedTargetsHash = stringValue(input.expectedTargetsHash)?.trim();
+        const maxPlacements = numberValue(input.maxPlacements);
         const receiptRequirements = isRecord(rawAction.receiptRequirements)
             ? rawAction.receiptRequirements
             : {};
@@ -933,7 +1005,13 @@ function sanitizeTargetSchedulerSweep(params) {
             rawAction.workspaceWide !== true ||
             rawAction.yoloEligible !== true ||
             receiptRequirements.nonTruncated !== true ||
+            receiptRequirements.expectedTargetSummary !== true ||
             !sameStrings(groupBy, SCHEDULER_SWEEP_RECEIPT_GROUPS) ||
+            !expectedTargets ||
+            !expectedTargetsHash ||
+            !Number.isInteger(maxPlacements) ||
+            maxPlacements <= 0 ||
+            maxPlacements > REFILL_SCHEDULER_MAX_PLACEMENTS ||
             !sameStrings(allowedSideEffects, SCHEDULER_SWEEP_ALLOWED_SIDE_EFFECTS) ||
             !sameStrings(forbiddenSideEffects, SCHEDULER_SWEEP_FORBIDDEN_SIDE_EFFECTS)) {
             continue;
@@ -955,6 +1033,9 @@ function sanitizeTargetSchedulerSweep(params) {
                 campaignIds,
                 tableIds,
                 sourceScopes,
+                expectedTargets,
+                expectedTargetsHash,
+                maxPlacements,
                 targetShapeRevision: params.expectedTargetShapeRevision,
                 stateRevision: params.expectedStateRevision,
                 requestKey,
@@ -972,6 +1053,7 @@ function sanitizeTargetSchedulerSweep(params) {
             forbiddenSideEffects: [...SCHEDULER_SWEEP_FORBIDDEN_SIDE_EFFECTS],
             receiptRequirements: {
                 nonTruncated: true,
+                expectedTargetSummary: true,
                 groupBy: [...SCHEDULER_SWEEP_RECEIPT_GROUPS],
             },
             actionKey,
@@ -1141,15 +1223,25 @@ function sanitizeRefillTargetPlanResult(result) {
     const paidRefreshNeededSenderIdSet = paidRefreshNeededSenderIds(senderRefillPlans);
     const blockers = sanitizeBlockers(result.blockers, selectedKeys, paidRefreshNeededSenderIdSet);
     const request = isRecord(result.request) ? result.request : {};
+    const sweepEligibleBySender = new Map();
+    for (const plan of senderPlans) {
+        const senderId = stringValue(plan.senderId);
+        const actionType = allowedActionType(plan.actionType);
+        if (senderId &&
+            actionType &&
+            numberValue(plan.remainingProjectedGap) > 0 &&
+            numberValue(plan.remainingReadyOrProjectedGap) === 0 &&
+            numberValue(plan.readyBuffer) > 0) {
+            sweepEligibleBySender.set(senderId, actionType);
+        }
+    }
     const schedulerSweepAction = sanitizeTargetSchedulerSweep({
         value: target.globalActionQueue,
-        selectedBySender,
+        sweepEligibleBySender,
         expectedWorkspaceId: stringValue(target.workspaceId),
         expectedTargetDate: stringValue(request.targetDate),
         expectedTargetShapeRevision: stringValue(result.targetShapeRevision),
         expectedStateRevision: stringValue(result.stateRevision),
-        remainingProjectedGap,
-        remainingReadyOrProjectedGap,
     });
     const globalActionQueue = schedulerSweepAction
         ? [schedulerSweepAction]

package/dist/tools/registry.d.ts

@@ -7838,6 +7838,54 @@ export declare const allTools: ({
                 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.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;