@sellable/mcp 0.1.552 → 0.1.553

package/dist/tools/refill-sends.js

@@ -1,6 +1,8 @@
 import { actionIds, classifyPaidInmailRefreshReceipt, collectPaidInmailRefreshActions, executeOneYoloPrimitive, firstGlobalAction, normalizeStrings, numberValue, recordValue, refreshPaidInmailCreditsWithRetry, stringValue, } from "./refill-executors.js";
 import { getRefillTargetPlan } from "./refill-target-plan.js";
 import { createWorkspaceContext, normalizeExplicitWorkspaceId, } from "./workspace-context.js";
+const REFILL_SEND_ACTION_TYPES = ["send_invite", "send_inmail_closed"];
+const REFILL_SEND_ACTION_TYPE_SET = new Set(REFILL_SEND_ACTION_TYPES);
 const DEFAULT_SCHEDULER_FORWARD_HOURS = 48;
 const MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
 function normalizeHorizonSendDays(value) {
@@ -48,10 +50,51 @@ function normalizeTargetDate(value) {
     }
     return trimmed;
 }
+function normalizeRefillActionTypes(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("actionTypes must be an array of supported refill lanes.");
+    }
+    if (value.some((actionType) => typeof actionType !== "string")) {
+        throw new Error(`Unsupported refill actionTypes. Supported values are ${REFILL_SEND_ACTION_TYPES.join(", ")}.`);
+    }
+    const normalized = normalizeStrings(value);
+    const unsupported = normalized.filter((actionType) => !REFILL_SEND_ACTION_TYPE_SET.has(actionType));
+    if (unsupported.length > 0) {
+        throw new Error(`Unsupported refill actionTypes: ${unsupported.join(", ")}. Supported values are ${REFILL_SEND_ACTION_TYPES.join(", ")}.`);
+    }
+    return normalized.length > 0
+        ? normalized
+        : undefined;
+}
+function normalizeExpectedPacketValue(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${field} must be a non-empty string when provided.`);
+    }
+    return value.trim();
+}
+function normalizeRefillSendsInput(input) {
+    const actionTypes = normalizeRefillActionTypes(input.actionTypes);
+    const expectedTargetShapeRevision = normalizeExpectedPacketValue(input.expectedTargetShapeRevision, "expectedTargetShapeRevision");
+    const expectedActionKey = normalizeExpectedPacketValue(input.expectedActionKey, "expectedActionKey");
+    const normalized = { ...input };
+    delete normalized.actionTypes;
+    delete normalized.expectedTargetShapeRevision;
+    delete normalized.expectedActionKey;
+    return {
+        ...normalized,
+        ...(actionTypes ? { actionTypes } : {}),
+        ...(expectedTargetShapeRevision ? { expectedTargetShapeRevision } : {}),
+        ...(expectedActionKey ? { expectedActionKey } : {}),
+    };
+}
 export const refillSendsToolDefinitions = [
     {
         name: "refill_sends",
-        description: "Typed command entrypoint for Sellable refill sends. Accepts --yolo semantics and optional sender selectors, then returns the bounded execution contract for the skill-led refill workflow. In --yolo, it may refresh stale paid InMail credit cache facts once, or execute exactly one safe primitive from target.globalActionQueue[0] (bounded existing-row preparation, bounded generated-message approval, receipt-proven same-source copy, or read-only wait) and reread. Same-source copy/source fallback is only safe after receipt-proven exhaustion: hasMoreFrontierRows:false, zero approvalCandidates, no stuckActiveCells, and no non-terminal approvedNotDispatched work. Wait primitives are gates, not competing goals, and carry absolute wait.deadlineAt when present. It does not run unbounded approval, lower paid InMail thresholds, switch source families, create campaigns, schedule sends, launch, archive, delete, or write scheduler rows.",
+        description: "Typed command entrypoint for Sellable refill sends. Accepts --yolo semantics and optional sender selectors, then returns the bounded execution contract for the skill-led refill workflow. In --yolo, it may refresh stale paid InMail credit cache facts once, or execute exactly one safe primitive from target.globalActionQueue[0] (bounded existing-row preparation, bounded generated-message approval, receipt-proven same-source copy, a request-scoped run_scheduler_sweep for an exact date, or a read-only wait) and reread. Same-source copy/source fallback is only safe after receipt-proven exhaustion: hasMoreFrontierRows:false, zero approvalCandidates, no stuckActiveCells, and no non-terminal approvedNotDispatched work. The exact-date sweep may schedule eligible workspace cells through existing product gates; it never sends directly or raw-writes scheduler fields. Wait primitives are gates, not competing goals, and carry absolute wait.deadlineAt when present. It does not run unbounded approval, lower paid InMail thresholds, switch source families, create campaigns, launch, archive, or delete.",
         inputSchema: {
             type: "object",
             properties: {
@@ -87,6 +130,14 @@ export const refillSendsToolDefinitions = [
                     items: { type: "string" },
                     description: "Optional sender display names to resolve through list_senders before campaign selection.",
                 },
+                actionTypes: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: ["send_invite", "send_inmail_closed"],
+                    },
+                    description: "Optional explicit refill lane. Omit to preserve planner inference; supported values are connection invites and paid InMail / unified Sales Nav cascades.",
+                },
                 horizonSendDays: {
                     type: "number",
                     minimum: 1,
@@ -121,6 +172,14 @@ export const refillSendsToolDefinitions = [
                     enum: ["approve", "mark_ready"],
                     description: 'Preparation mode for the final packet. Use "approve" only when the user asked to fill/schedule sender sends; otherwise default to "mark_ready".',
                 },
+                expectedTargetShapeRevision: {
+                    type: "string",
+                    description: "Optional targetShapeRevision from an already rendered and approved packet. A mismatch returns approval_scope_changed before any refresh or mutation.",
+                },
+                expectedActionKey: {
+                    type: "string",
+                    description: "Optional actionKey from the approved packet's first global action. A mismatch returns approval_scope_changed before any refresh or mutation.",
+                },
             },
             required: [],
             additionalProperties: false,
@@ -128,6 +187,9 @@ export const refillSendsToolDefinitions = [
     },
 ];
 export function refillSendsCommand(input = {}) {
+    return buildRefillSendsCommand(normalizeRefillSendsInput(input));
+}
+function buildRefillSendsCommand(input) {
     const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
     const senders = normalizeStrings(input.senders);
     const senderIds = normalizeStrings(input.senderIds);
@@ -142,6 +204,7 @@ export function refillSendsCommand(input = {}) {
         : normalizeHorizonSendDays(input.horizonSendDays);
     const intent = input.intent ?? "plain";
     const approvalMode = input.approvalMode ?? (yolo ? "approve" : "mark_ready");
+    const actionTypes = input.actionTypes;
     const senderScope = hasSenderSelectors
         ? "selected_senders"
         : yolo
@@ -161,6 +224,7 @@ export function refillSendsCommand(input = {}) {
         workspaceId,
         workspaceResolution: workspaceId ? "explicit" : "active_config",
         intent,
+        ...(actionTypes ? { actionTypes } : {}),
         targetDate,
         untilDate,
         horizonSendDays,
@@ -201,7 +265,7 @@ export function refillSendsCommand(input = {}) {
             "A skill cannot create or invoke /goal by itself. If this refill is already running inside an active Codex goal, keep that goal open until every selected sender lane is horizon-filled by projected coverage (sent + scheduled), Christian explicitly stops/statuses the run, or a concrete non-scheduler blocker appears.",
             `Call get_refill_target_plan({ intent: "${intent}"${workspaceId ? `, workspaceId: "${workspaceId}"` : ""}${input.campaignId ? `, campaignId: "${input.campaignId}"` : ""}${input.tableId ? `, tableId: "${input.tableId}"` : ""}${senderIds.length > 0 ? `, senderIds: ${JSON.stringify(senderIds)}` : ""}${senderNames.length > 0
                 ? `, senderNames: ${JSON.stringify(senderNames)}`
-                : ""}${senders.length > 0 ? `, senders: ${JSON.stringify(senders)}` : ""}${targetDate
+                : ""}${senders.length > 0 ? `, senders: ${JSON.stringify(senders)}` : ""}${actionTypes ? `, actionTypes: ${JSON.stringify(actionTypes)}` : ""}${targetDate
                 ? `, targetDate: "${targetDate}"`
                 : untilDate
                     ? `, untilDate: "${untilDate}"`
@@ -210,10 +274,11 @@ export function refillSendsCommand(input = {}) {
                         : `, 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.",
             "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 remainingReadyOrProjectedGap is 0 but remainingProjectedGap is positive, 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 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.",
             `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
@@ -231,7 +296,7 @@ export function refillSendsCommand(input = {}) {
             "Fresh reread get_campaign_refill_state immediately before any import, prep, approval, or horizon-fill mutation.",
             "Maintain a target-window saturation ledger per selected sender from get_refill_target_plan: selected days, gross capacity, actual sent counts, future scheduler-owned scheduled counts, projected counts, ready-to-schedule buffer, remaining projected gap, paid InMail threshold feasibility, targetShapeRevision, stateRevision, and next MCP primitive.",
             "Source/fallback primitives require receipt-proven exhaustion: existingRowFrontier.hasMoreFrontierRows:false, approvalCandidates:0, no fresh active prep, no stuckActiveCells, and no non-terminal approvedNotDispatched rows. Treat anomalies, stuckActiveCells, and non-terminal approvedNotDispatched as diagnose-and-report gates, not exhaustion. Terminal approvedNotDispatched blockers may be reported and then the ladder can proceed.",
-            "In manual/non-yolo, scheduled, and --yolo modes, this tool may automatically refresh stale or missing paid-InMail credit facts once per selected sender when the first target plan returns refresh_paid_inmail_credits candidates. This is the only newly allowed automatic write in manual/non-yolo mode; it reruns get_refill_target_plan and returns autoPaidInmailRefresh with attemptedSenderIds, refreshedPaidInmailSenderIds, failedPaidInmailRefreshes, and the post-refresh targetPlan before any prep/source-copy/bounded-approval/read-only wait action is chosen.",
+            "In manual/non-yolo, scheduled, and --yolo modes, this tool may automatically refresh stale or missing paid-InMail credit facts once per selected sender when the first target plan returns refresh_paid_inmail_credits candidates. This is the only newly allowed automatic write in manual/non-yolo mode; it reruns get_refill_target_plan and returns autoPaidInmailRefresh with attemptedSenderIds, refreshedPaidInmailSenderIds, failedPaidInmailRefreshes, and the post-refresh targetPlan before any prep/source-copy/bounded-approval/exact-date-sweep/read-only-wait action is chosen.",
             "Freshness gate precedes scheduler wait: if any selected target.senderRefillPlans[].paidInmail.status is missing_credit_facts or stale_credit_facts, or the target plan contains refresh_paid_inmail_credits, do not enter wait_for_scheduler even when remainingReadyOrProjectedGap is 0; refresh exact sender credit facts once, reread get_refill_target_plan, then choose scheduler wait only if freshness is clean.",
             "Scheduler-run receipt interpretation: cellsConsidered is allocation-attempt count, readyCellsFound is ready inventory before prefilters, and campaignScopeSummary must include the selected campaign/table before inferring it was ready-but-blocked. Read prefiltered, skipped, and deferred separately. For ready closed-InMail cells with stale paid-credit facts, route to refresh_paid_inmail_credits_then_rerun once, then rerun/status. wait_for_capacity_or_window means report loaded/capped/waiting and do not source or prep more rows. no_ready_cells_continue_refill_prep means return to the refill/prep ladder.",
             "For wait_for_active_work and wait_for_scheduler, honor the receipt's absolute wait.deadlineAt when present. If the deadline is expired on this call, escalate to diagnostics with the receipt evidence instead of issuing another blind wait.",
@@ -241,9 +306,9 @@ export function refillSendsCommand(input = {}) {
             "Do not complete a fill/schedule request until a final get_refill_target_plan or refill-state reread proves projected coverage (sent + scheduled) fills the scheduler-forward target window. Treat awaiting_scheduler_after_ready_buffer as loaded, awaiting scheduler when ready buffer covers the gap; do not import/prep more rows in that state, and keep polling unless Christian stops/statuses the run or a concrete non-scheduler blocker such as paid_inmail_below_threshold appears.",
         ],
         approvalContract: yolo
-            ? "Auto-accept only the rendered bounded refill target packet after get_refill_target_plan and fresh reread. Execute one globally ranked primitive from target.globalActionQueue at a time, then rerun get_refill_target_plan before taking another action. Continue through every safe prep/source-copy/bounded-approval/read-only wait action inside that packet, but source-copy/fallback requires receipt-proven exhaustion of earlier ready/prep/approval rungs. Unbounded approval, start_campaign, source-family switches, threshold changes, and campaign creation require their own explicit gates. After each safe action, rerun get_refill_target_plan; keep going while targetShapeRevision is stable and projected coverage (sent + scheduled) progresses toward the target, even though stateRevision changes. Ready-to-schedule rows are buffer, not completion. If ready buffer covers the projected gap, use only persistent read-only scheduler wait/reread and keep the run open until projected coverage fills or Christian stops/statuses it. Stop immediately if targetShapeRevision changes because sender set, route, ids, caps, dates, blockers, action class, paid InMail threshold feasibility, side-effect class, or receipt exhaustion proof drifts. --yolo does not authorize lowering paid InMail thresholds or creating connection campaigns."
+            ? "Auto-accept only the rendered bounded refill target packet after get_refill_target_plan and fresh reread. Execute one globally ranked primitive from target.globalActionQueue at a time, then rerun get_refill_target_plan before taking another action. Continue through every safe prep/source-copy/bounded-approval/exact-date-sweep/read-only-wait action inside that packet, but source-copy/fallback requires receipt-proven exhaustion of earlier ready/prep/approval rungs. Unbounded approval, start_campaign, source-family switches, threshold changes, and campaign creation require their own explicit gates. After each safe action, rerun get_refill_target_plan; keep going while targetShapeRevision is stable and projected coverage (sent + scheduled) progresses toward the target, even though stateRevision changes. Ready-to-schedule rows are buffer, not completion. If ready buffer covers the projected gap and the exact-date run_scheduler_sweep is target.globalActionQueue[0], execute it once and fully reread. Only non-exact or no-sweep scheduler waits are read-only; use a persistent read-only scheduler wait/reread and keep the run open until projected coverage fills or Christian stops/statuses it. Stop immediately if targetShapeRevision changes because workspace, sender set, campaign/table/stable source identity, configured caps, exact date/window, lane, or the approved action/side-effect envelope drifts. Treat coverage, blockers, receipts, timestamps, and current action progress as stateRevision changes inside that envelope. --yolo does not authorize lowering paid InMail thresholds or creating connection campaigns."
             : hasSenderSelectors
-                ? "Before mutation, post the full bounded refill packet in normal chat as Markdown, including workspace, sender scope, campaign table, exact ids, caps/dates, gross target, sent count, scheduled count, projected count, ready buffer, remaining projected gap, paid InMail threshold feasibility, targetShapeRevision/stateRevision, side effects, forbidden actions, and stop condition. Then ask the final Accept/Decline structured approval question with a compact body that refers back to the posted packet instead of duplicating it. Only ask when get_refill_target_plan reports a positive remaining projected/ready gap. If target is complete by projected coverage, no-op without approval. If ready buffer covers the projected gap, run only persistent read-only scheduler wait/reread and keep the run open until projected coverage fills or Christian stops/statuses it. Threshold changes and campaign creation need separate explicit approval."
+                ? "Before mutation, post the full bounded refill packet in normal chat as Markdown, including workspace, sender scope, campaign table, exact ids, caps/dates, gross target, sent count, scheduled count, projected count, ready buffer, remaining projected gap, paid InMail threshold feasibility, targetShapeRevision/stateRevision, side effects, forbidden actions, and stop condition. Then ask the final Accept/Decline structured approval question with a compact body that refers back to the posted packet instead of duplicating it. Only ask when get_refill_target_plan reports a positive remaining projected/ready gap. If target is complete by projected coverage, no-op without approval. If ready buffer covers the projected gap and the approved exact-date run_scheduler_sweep is target.globalActionQueue[0], execute it once and fully reread. Only non-exact or no-sweep scheduler waits are read-only; keep the run open until projected coverage fills or Christian stops/statuses it. Threshold changes and campaign creation need separate explicit approval."
                 : "Ask which eligible enrolled senders to refill first, then, before mutation, post the full bounded refill packet in normal chat as Markdown and ask the final Accept/Decline structured approval question with a compact body that refers back to the posted packet.",
         forbiddenActions: [
             "start_campaign outside an exact selected PAUSED campaign-backed refill packet",
@@ -276,6 +341,7 @@ export function refillSendsCommand(input = {}) {
                     senders,
                     senderIds,
                     senderNames,
+                    ...(actionTypes ? { actionTypes } : {}),
                     targetDate,
                     untilDate,
                     horizonSendDays,
@@ -284,6 +350,14 @@ export function refillSendsCommand(input = {}) {
                     intent,
                     approvalMode,
                     workspaceId,
+                    ...(input.expectedTargetShapeRevision
+                        ? {
+                            expectedTargetShapeRevision: input.expectedTargetShapeRevision,
+                        }
+                        : {}),
+                    ...(input.expectedActionKey
+                        ? { expectedActionKey: input.expectedActionKey }
+                        : {}),
                 },
             },
         },
@@ -307,6 +381,7 @@ function targetPlanInputFor(input = {}) {
         ...(senderIds.length > 0 ? { senderIds } : {}),
         ...(senderNames.length > 0 ? { senderNames } : {}),
         ...(senders.length > 0 ? { senders } : {}),
+        ...(input.actionTypes ? { actionTypes: input.actionTypes } : {}),
         ...(targetDate
             ? { targetDate }
             : untilDate
@@ -327,6 +402,24 @@ function targetPlanFingerprint(plan) {
         generatedAt: stringValue(root?.generatedAt) ?? null,
     };
 }
+function approvedPacketComparison(input, targetPlan) {
+    const root = recordValue(targetPlan);
+    const action = recordValue(firstGlobalAction(targetPlan));
+    const actualTargetShapeRevision = stringValue(root?.targetShapeRevision) ?? null;
+    const actualActionKey = stringValue(action?.actionKey) ?? null;
+    const shapeChanged = Boolean(input.expectedTargetShapeRevision &&
+        input.expectedTargetShapeRevision !== actualTargetShapeRevision);
+    const actionChanged = Boolean(input.expectedActionKey && input.expectedActionKey !== actualActionKey);
+    return {
+        changed: shapeChanged || actionChanged,
+        expectedTargetShapeRevision: input.expectedTargetShapeRevision ?? null,
+        actualTargetShapeRevision,
+        expectedActionKey: input.expectedActionKey ?? null,
+        actualActionKey,
+        shapeChanged,
+        actionChanged,
+    };
+}
 function paidRefreshApprovalPacket(params) {
     const action = params.action.action ?? {};
     const ids = actionIds(action);
@@ -358,12 +451,15 @@ function paidRefreshOptionsFromApprovalPacket(packet) {
     };
 }
 export async function executeRefillSendsCommand(input = {}) {
-    const yolo = input.yolo === true;
-    const executionMode = input.executionMode ?? (yolo ? "yolo" : "manual");
-    const mustHaveWorkspace = yolo || input.requireWorkspace === true || executionMode === "scheduled";
+    const normalizedInput = normalizeRefillSendsInput(input);
+    const yolo = normalizedInput.yolo === true;
+    const executionMode = normalizedInput.executionMode ?? (yolo ? "yolo" : "manual");
+    const mustHaveWorkspace = yolo ||
+        normalizedInput.requireWorkspace === true ||
+        executionMode === "scheduled";
     const workspaceContext = mustHaveWorkspace
         ? createWorkspaceContext({
-            workspaceId: input.workspaceId,
+            workspaceId: normalizedInput.workspaceId,
             executionMode,
             toolName: "refill_sends",
         })
@@ -372,9 +468,12 @@ export async function executeRefillSendsCommand(input = {}) {
         return workspaceContext;
     }
     const scopedInput = workspaceContext && workspaceContext.ok
-        ? { ...input, workspaceId: workspaceContext.context.workspaceId }
-        : input;
-    const command = refillSendsCommand(scopedInput);
+        ? {
+            ...normalizedInput,
+            workspaceId: workspaceContext.context.workspaceId,
+        }
+        : normalizedInput;
+    const command = buildRefillSendsCommand(scopedInput);
     const workspaceId = workspaceContext && workspaceContext.ok
         ? workspaceContext.context.workspaceId
         : normalizeExplicitWorkspaceId(scopedInput.workspaceId);
@@ -399,6 +498,35 @@ export async function executeRefillSendsCommand(input = {}) {
     }
     const targetPlanInput = targetPlanInputFor(scopedInput);
     const targetPlanBeforePaidRefresh = await getRefillTargetPlan(targetPlanInput);
+    const approvedPacket = approvedPacketComparison(scopedInput, targetPlanBeforePaidRefresh);
+    if (approvedPacket.changed) {
+        return {
+            ...command,
+            ok: false,
+            code: "approval_scope_changed",
+            targetPlan: targetPlanBeforePaidRefresh,
+            targetPlanBeforePaidRefresh: null,
+            targetPlanBeforeYoloPrimitive: null,
+            ...approvedPacket,
+            autoPaidInmailRefresh: {
+                enabled: false,
+                status: "skipped_approval_scope_changed",
+                refreshedPaidInmailSenderIds: [],
+                failedPaidInmailRefreshes: [],
+                attemptedSenderIds: [],
+                targetPlanReread: false,
+                workspaceId,
+                workspaceResolution: workspaceId ? "explicit" : "active_config",
+                note: "Approved refill scope changed before paid-credit refresh or primitive execution.",
+            },
+            yoloExecution: {
+                enabled: yolo,
+                status: "approval_scope_changed",
+                selectedAction: firstGlobalAction(targetPlanBeforePaidRefresh),
+                targetPlanReread: false,
+            },
+        };
+    }
     const refreshActions = collectPaidInmailRefreshActions(targetPlanBeforePaidRefresh);
     const refreshedPaidInmailSenderIds = [];
     const failedPaidInmailRefreshes = [];

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

@@ -10,6 +10,7 @@ const SAFE_PACKET_ACTION_TYPES = new Set([
     "approve_messages",
     "start_paused_campaign",
     "rerun_errored_cells",
+    "run_scheduler_sweep",
     "wait_for_scheduler",
     "wait_for_active_work",
     "wait_for_source_import",
@@ -73,6 +74,21 @@ const PREP_FAILURE_RECOMMENDED_ACTIONS = new Set([
     "approve_or_repair_approval_cells",
     "inspect_rows",
 ]);
+const SCHEDULER_SWEEP_ALLOWED_SIDE_EFFECTS = [
+    "schedule any eligible workspace cells on the approved date within scheduler gates",
+];
+const SCHEDULER_SWEEP_FORBIDDEN_SIDE_EFFECTS = [
+    "send directly",
+    "write scheduler fields directly",
+    "change campaign state",
+    "change sender limits",
+    "change source selection",
+];
+const SCHEDULER_SWEEP_RECEIPT_GROUPS = [
+    "campaignId",
+    "tableId",
+    "actionType",
+];
 async function postRefillTargetPlan(body, workspaceId) {
     const api = getApi();
     const requestOptions = workspaceRequestOptions(workspaceId);
@@ -515,6 +531,7 @@ function sanitizeStructuredAction(action, selectedBySender, mode, rank) {
             : null,
         stopCondition: stringValue(action.stopCondition) ?? "",
         yoloEligible,
+        actionKey: stringValue(action.actionKey),
         capSaturated: booleanValue(action.capSaturated) === true ? true : undefined,
         prepFailureDiagnosis: sanitizePrepFailureDiagnosis(action.prepFailureDiagnosis),
     };
@@ -814,6 +831,154 @@ function buildSanitizedGlobalActionQueue(senderRefillPlans) {
         rank: index + 1,
     }));
 }
+function sortedUniqueStrings(value) {
+    return [...new Set(stringArray(value))].sort();
+}
+function sameStrings(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+function sanitizeSchedulerSweepSourceScopes(value) {
+    if (!Array.isArray(value))
+        return [];
+    const scopes = value.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const campaignId = stringValue(entry.campaignId)?.trim();
+        const tableId = stringValue(entry.tableId)?.trim();
+        const sourceLeadListId = stringValue(entry.sourceLeadListId)?.trim();
+        const leadSourceProvider = stringValue(entry.leadSourceProvider)?.trim();
+        if (!campaignId ||
+            !tableId ||
+            !sourceLeadListId ||
+            !leadSourceProvider) {
+            return [];
+        }
+        return [
+            { campaignId, tableId, sourceLeadListId, leadSourceProvider },
+        ];
+    });
+    const unique = new Map(scopes.map((scope) => [
+        [
+            scope.campaignId,
+            scope.tableId,
+            scope.sourceLeadListId,
+            scope.leadSourceProvider,
+        ].join(":"),
+        scope,
+    ]));
+    return [...unique.values()].sort((a, b) => {
+        if (a.campaignId !== b.campaignId) {
+            return a.campaignId.localeCompare(b.campaignId);
+        }
+        return a.tableId.localeCompare(b.tableId);
+    });
+}
+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) {
+        return null;
+    }
+    const expectedSenderIds = [...params.selectedBySender.keys()].sort();
+    const expectedActionTypes = [
+        ...new Set(params.selectedBySender.values()),
+    ].sort();
+    if (expectedSenderIds.length === 0 || expectedActionTypes.length === 0) {
+        return null;
+    }
+    for (const rawAction of params.value) {
+        if (!isRecord(rawAction) || rawAction.type !== "run_scheduler_sweep") {
+            continue;
+        }
+        const input = isRecord(rawAction.toolInput) ? rawAction.toolInput : {};
+        const actionKey = stringValue(rawAction.actionKey)?.trim();
+        const requestKey = stringValue(input.requestKey)?.trim();
+        const senderIds = sortedUniqueStrings(input.senderIds);
+        const actionTypes = sortedUniqueStrings(input.actionTypes).filter((actionType) => allowedActionType(actionType) === actionType);
+        const campaignIds = sortedUniqueStrings(input.campaignIds);
+        const tableIds = sortedUniqueStrings(input.tableIds);
+        const sourceScopes = sanitizeSchedulerSweepSourceScopes(input.sourceScopes);
+        const receiptRequirements = isRecord(rawAction.receiptRequirements)
+            ? rawAction.receiptRequirements
+            : {};
+        const groupBy = stringArray(receiptRequirements.groupBy);
+        const allowedSideEffects = stringArray(rawAction.allowedSideEffects);
+        const forbiddenSideEffects = stringArray(rawAction.forbiddenSideEffects);
+        const rawActionType = allowedActionType(rawAction.actionType);
+        if (input.action !== "run" ||
+            input.workspaceId !== params.expectedWorkspaceId ||
+            input.targetDate !== params.expectedTargetDate ||
+            input.targetDateKey !== params.expectedTargetDate ||
+            input.targetShapeRevision !== params.expectedTargetShapeRevision ||
+            input.stateRevision !== params.expectedStateRevision ||
+            !actionKey ||
+            requestKey !== actionKey ||
+            !sameStrings(senderIds, expectedSenderIds) ||
+            !sameStrings(actionTypes, expectedActionTypes) ||
+            (expectedActionTypes.length === 1 &&
+                rawActionType !== expectedActionTypes[0]) ||
+            campaignIds.length === 0 ||
+            tableIds.length === 0 ||
+            sourceScopes.length === 0 ||
+            sourceScopes.some((scope) => !campaignIds.includes(scope.campaignId) ||
+                !tableIds.includes(scope.tableId)) ||
+            rawAction.toolName !== "run_scheduler_sweep" ||
+            rawAction.sideEffectClass !== "scheduler_placement" ||
+            rawAction.workspaceWide !== true ||
+            rawAction.yoloEligible !== true ||
+            receiptRequirements.nonTruncated !== true ||
+            !sameStrings(groupBy, SCHEDULER_SWEEP_RECEIPT_GROUPS) ||
+            !sameStrings(allowedSideEffects, SCHEDULER_SWEEP_ALLOWED_SIDE_EFFECTS) ||
+            !sameStrings(forbiddenSideEffects, SCHEDULER_SWEEP_FORBIDDEN_SIDE_EFFECTS)) {
+            continue;
+        }
+        return {
+            rank: 1,
+            type: "run_scheduler_sweep",
+            actionType: rawActionType,
+            toolName: "run_scheduler_sweep",
+            sideEffectClass: "scheduler_placement",
+            ids: {},
+            toolInput: {
+                action: "run",
+                workspaceId: params.expectedWorkspaceId,
+                targetDate: params.expectedTargetDate,
+                targetDateKey: params.expectedTargetDate,
+                senderIds,
+                actionTypes,
+                campaignIds,
+                tableIds,
+                sourceScopes,
+                targetShapeRevision: params.expectedTargetShapeRevision,
+                stateRevision: params.expectedStateRevision,
+                requestKey,
+            },
+            inputSummary: stringValue(rawAction.inputSummary) ?? "",
+            reason: stringValue(rawAction.reason) ?? "",
+            prerequisites: stringArray(rawAction.prerequisites),
+            rereadAfter: rawAction.rereadAfter === "get_refill_target_plan"
+                ? "get_refill_target_plan"
+                : null,
+            stopCondition: stringValue(rawAction.stopCondition) ?? "",
+            yoloEligible: true,
+            workspaceWide: true,
+            allowedSideEffects: [...SCHEDULER_SWEEP_ALLOWED_SIDE_EFFECTS],
+            forbiddenSideEffects: [...SCHEDULER_SWEEP_FORBIDDEN_SIDE_EFFECTS],
+            receiptRequirements: {
+                nonTruncated: true,
+                groupBy: [...SCHEDULER_SWEEP_RECEIPT_GROUPS],
+            },
+            actionKey,
+        };
+    }
+    return null;
+}
 function paidRefreshNeededSenderIds(senderRefillPlans) {
     const senderIds = new Set();
     for (const plan of senderRefillPlans) {
@@ -975,7 +1140,20 @@ function sanitizeRefillTargetPlanResult(result) {
     const senderRefillPlans = sanitizeStructuredSenderPlans(target.senderRefillPlans, selectedBySender);
     const paidRefreshNeededSenderIdSet = paidRefreshNeededSenderIds(senderRefillPlans);
     const blockers = sanitizeBlockers(result.blockers, selectedKeys, paidRefreshNeededSenderIdSet);
-    const globalActionQueue = buildSanitizedGlobalActionQueue(senderRefillPlans);
+    const request = isRecord(result.request) ? result.request : {};
+    const schedulerSweepAction = sanitizeTargetSchedulerSweep({
+        value: target.globalActionQueue,
+        selectedBySender,
+        expectedWorkspaceId: stringValue(target.workspaceId),
+        expectedTargetDate: stringValue(request.targetDate),
+        expectedTargetShapeRevision: stringValue(result.targetShapeRevision),
+        expectedStateRevision: stringValue(result.stateRevision),
+        remainingProjectedGap,
+        remainingReadyOrProjectedGap,
+    });
+    const globalActionQueue = schedulerSweepAction
+        ? [schedulerSweepAction]
+        : buildSanitizedGlobalActionQueue(senderRefillPlans);
     const hasTerminalNoActionBlocker = globalActionQueue.length === 0 &&
         blockers.some((blocker) => TERMINAL_NO_ACTION_BLOCKER_CODES.has(String(blocker.code)));
     const status = remainingProjectedGap === 0

package/dist/tools/registry.d.ts

@@ -7546,6 +7546,14 @@ export declare const allTools: ({
                 type: string;
                 description: string;
             };
+            requestKey: {
+                type: string;
+                description: string;
+            };
+            targetShapeRevision: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;

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

@@ -3,6 +3,8 @@ type RunSchedulerSweepInput = {
     workspaceId: string;
     action?: SchedulerRunAction;
     targetDate?: string;
+    requestKey?: string;
+    targetShapeRevision?: string;
 };
 export declare const schedulerRunToolDefinitions: {
     name: string;
@@ -23,6 +25,14 @@ export declare const schedulerRunToolDefinitions: {
                 type: string;
                 description: string;
             };
+            requestKey: {
+                type: string;
+                description: string;
+            };
+            targetShapeRevision: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/scheduler-run.js

@@ -21,6 +21,14 @@ function normalizeTargetDate(value) {
     }
     return targetDate;
 }
+function normalizeOptionalScopeValue(value, field) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${field} must be a non-empty string when provided.`);
+    }
+    return value.trim();
+}
 export const schedulerRunToolDefinitions = [
     {
         name: "run_scheduler_sweep",
@@ -41,6 +49,14 @@ export const schedulerRunToolDefinitions = [
                     type: "string",
                     description: "Optional one exact sender-local date (YYYY-MM-DD) to scope scheduler placement/status. The run remains workspace-wide inside that date.",
                 },
+                requestKey: {
+                    type: "string",
+                    description: "Optional deterministic planner action key used to attach to or replay the same exact scheduler attempt.",
+                },
+                targetShapeRevision: {
+                    type: "string",
+                    description: "Optional stable approved refill target-shape revision associated with requestKey.",
+                },
             },
             required: ["workspaceId"],
             additionalProperties: false,
@@ -54,6 +70,8 @@ export async function runSchedulerSweep(input) {
     }
     const action = input.action ?? "run";
     const targetDate = normalizeTargetDate(input.targetDate);
+    const requestKey = normalizeOptionalScopeValue(input.requestKey, "requestKey");
+    const targetShapeRevision = normalizeOptionalScopeValue(input.targetShapeRevision, "targetShapeRevision");
     if (action !== "run" && action !== "status") {
         throw new Error('action must be "run" or "status" for run_scheduler_sweep.');
     }
@@ -61,5 +79,7 @@ export async function runSchedulerSweep(input) {
         workspaceId,
         action,
         ...(targetDate ? { targetDate } : {}),
+        ...(requestKey ? { requestKey } : {}),
+        ...(targetShapeRevision ? { targetShapeRevision } : {}),
     }, workspaceId);
 }

package/package.json

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