@sellable/mcp 0.1.532 → 0.1.533

package/dist/refill-run-loop.js

@@ -19,6 +19,34 @@ const REFILL_DONE_REASONS = new Set([
     "not_an_evergreen_workspace",
     "no_refillable_campaigns",
 ]);
+const SCHEDULER_RUN_ENVELOPE_STATUSES = new Set([
+    "ran",
+    "attached",
+    "backoff",
+    "window_closed_noop",
+    "failed",
+]);
+const SCHEDULER_RUN_RECEIPT_STATUSES = new Set([
+    "ran",
+    "window_closed_noop",
+    "failed",
+]);
+const SCHEDULER_RUN_SKIP_REASONS = [
+    "window_closed",
+    "daily_limit",
+    "cooldown",
+    "sender_gate",
+    "credit_threshold",
+    "billing_blocked",
+    "duplicate_lead",
+    "no_senders",
+    "other",
+];
+const SCHEDULER_RUN_HARD_BLOCK_REASONS = new Set([
+    "billing_blocked",
+    "credit_threshold",
+    "cooldown",
+]);
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -40,6 +68,89 @@ function arrayValue(value) {
 function hasBlocker(value, blocker) {
     return isRecord(value) && value.blocker === blocker;
 }
+function schedulerRunSkipReasons(value) {
+    const raw = recordValue(value) ?? {};
+    const normalized = {};
+    for (const reason of SCHEDULER_RUN_SKIP_REASONS) {
+        normalized[reason] = numberValue(raw[reason]) ?? 0;
+    }
+    return normalized;
+}
+function dominantSchedulerRunSkipReason(skipReasons) {
+    let dominant = null;
+    let dominantCount = 0;
+    for (const reason of SCHEDULER_RUN_SKIP_REASONS) {
+        const count = skipReasons[reason] ?? 0;
+        if (count > dominantCount) {
+            dominant = reason;
+            dominantCount = count;
+        }
+    }
+    return dominantCount > 0 ? dominant : null;
+}
+function sanitizeSchedulerRunReceipt(raw) {
+    const envelope = recordValue(raw);
+    if (!envelope)
+        return null;
+    const status = stringValue(envelope.status);
+    if (!status || !SCHEDULER_RUN_ENVELOPE_STATUSES.has(status))
+        return null;
+    const retryAfterMs = envelope.retryAfterMs == null ? null : numberValue(envelope.retryAfterMs);
+    if (envelope.retryAfterMs != null && retryAfterMs == null)
+        return null;
+    const receiptInput = envelope.receipt;
+    let receipt = null;
+    let dominantSkipReason = null;
+    if (receiptInput != null) {
+        const rawReceipt = recordValue(receiptInput);
+        if (!rawReceipt)
+            return null;
+        const receiptStatus = stringValue(rawReceipt.status);
+        if (!receiptStatus || !SCHEDULER_RUN_RECEIPT_STATUSES.has(receiptStatus)) {
+            return null;
+        }
+        const cellsConsidered = numberValue(rawReceipt.cellsConsidered);
+        const cellsScheduled = numberValue(rawReceipt.cellsScheduled);
+        const cellsSkipped = numberValue(rawReceipt.cellsSkipped);
+        const cellsDeferred = numberValue(rawReceipt.cellsDeferred);
+        const tablesFilteredForNoCapacity = numberValue(rawReceipt.tablesFilteredForNoCapacity);
+        if (cellsConsidered == null ||
+            cellsScheduled == null ||
+            cellsSkipped == null ||
+            cellsDeferred == null ||
+            tablesFilteredForNoCapacity == null) {
+            return null;
+        }
+        const skipReasons = schedulerRunSkipReasons(rawReceipt.skipReasons);
+        dominantSkipReason = dominantSchedulerRunSkipReason(skipReasons);
+        receipt = {
+            status: receiptStatus,
+            cellsConsidered,
+            cellsScheduled,
+            cellsSkipped,
+            cellsDeferred,
+            tablesFilteredForNoCapacity,
+            skipReasons,
+        };
+    }
+    return {
+        status,
+        retryAfterMs,
+        receipt,
+        dominantSkipReason,
+        hardBlocked: dominantSkipReason != null &&
+            SCHEDULER_RUN_HARD_BLOCK_REASONS.has(dominantSkipReason),
+    };
+}
+function schedulerRunReceiptIsFreshZeroScheduled(schedulerRunReceipt) {
+    const status = stringValue(schedulerRunReceipt?.status);
+    const fresh = status === "ran" || status === "window_closed_noop";
+    if (!fresh)
+        return false;
+    const receipt = recordValue(schedulerRunReceipt?.receipt);
+    return (status === "window_closed_noop" ||
+        numberValue(receipt?.cellsScheduled) === 0);
+}
 function isLeaseLost(value) {
     return hasBlocker(value, "lease_lost");
 }
@@ -1013,22 +1124,34 @@ async function verifySchedulerWait(input, deps, ctx, action, budgets) {
     const enteredAt = stringValue(progress.schedulerWaitEnteredAt) ??
         (deps.now?.() ?? new Date()).toISOString();
     const jitFired = booleanValue(progress.schedulerJitFired) ?? false;
+    let schedulerRunReceipt = recordValue(progress.schedulerRunReceipt) ?? null;
     if (!jitFired) {
         const senderId = actionSenderId(action);
         if (senderId) {
             await deps.executors.refreshPaidInmailCreditsWithRetry(senderId, input.workspaceId);
         }
         if (deps.requestSchedulerRun) {
-            await deps.requestSchedulerRun(input.workspaceId);
+            try {
+                schedulerRunReceipt = sanitizeSchedulerRunReceipt(await deps.requestSchedulerRun(input.workspaceId));
+            }
+            catch {
+                schedulerRunReceipt = null;
+            }
         }
         ctx.runState = mergeRunState(ctx.runState, {
             progress: mergeProgress(ctx, {
                 schedulerWaitEnteredAt: enteredAt,
                 schedulerJitFired: true,
+                ...(schedulerRunReceipt ? { schedulerRunReceipt } : {}),
             }),
         });
     }
-    for (let poll = 0; poll < budgets.maxSchedulerReadbacks; poll += 1) {
+    const zeroScheduledFresh = schedulerRunReceiptIsFreshZeroScheduled(schedulerRunReceipt);
+    // EDGE-2: the on-demand run only executes placement; cron can still process
+    // due/timed-out cells later. We still do one readback, then avoid burning the
+    // full wait budget when the fresh receipt says nothing was placeable now.
+    const readbackBudget = zeroScheduledFresh ? 1 : budgets.maxSchedulerReadbacks;
+    for (let poll = 0; poll < readbackBudget; poll += 1) {
         const fresh = await deps.readPlan({
             workspaceId: input.workspaceId,
             intent: input.intent,

package/dist/server.js

@@ -45,6 +45,7 @@ import { allTools } from "./tools/registry.js";
 import { getRows, getTableRows, getTableRowsMinimal } from "./tools/rows.js";
 import { addRubricItem, checkRubric, deleteRubricItem, draftRubrics, saveRubrics, selectNecessaryRubrics, updateRubricItem, waitForRubricResults, } from "./tools/rubrics.js";
 import { getSchedulerFillCapacity } from "./tools/scheduler-fill-capacity.js";
+import { runSchedulerSweep } from "./tools/scheduler-run.js";
 import { getSenderRoutingTool, setSenderRoutingTool, } from "./tools/sender-routing.js";
 import { getSender, listSenders, refreshPaidInmailCredits, } from "./tools/senders.js";
 import { attachRecommendedSequence, attachSequence, createWorkflowTable, } from "./tools/sequencer.js";
@@ -235,6 +236,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_scheduler_fill_capacity":
                 result = await getSchedulerFillCapacity(args);
                 break;
+            case "run_scheduler_sweep":
+                result = await runSchedulerSweep(args);
+                break;
             case "refill_sends":
                 result = await executeRefillSendsCommand(args);
                 break;

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

@@ -5,6 +5,7 @@ import { runRefillV2Loop } from "../refill-run-loop.js";
 import { getPrepareCampaignMessagesStatus } from "./campaign-message-preparation.js";
 import { getRefillPlanV2 } from "./evergreen-refill-plan.js";
 import { executeOneYoloPrimitive, executeStartCampaignPrimitive, prepareRowSelectorValue, refillPrepareRequestHash, refreshPaidInmailCreditsWithRetry, } from "./refill-executors.js";
+import { runSchedulerSweep } from "./scheduler-run.js";
 const FORBIDDEN_ACTIONS = [
     "Do not schedule sends.",
     "Do not send messages.",
@@ -152,6 +153,7 @@ export async function refillSendsV2Command(input) {
         localState: {
             writeRefillWorkspaceState,
         },
+        requestSchedulerRun: (workspaceId) => runSchedulerSweep({ workspaceId, action: "run" }),
     });
     return {
         ...(await maybeAddLostFenceGuidance(result, { ...input, workspaceId })),

package/dist/tools/registry.d.ts

@@ -7370,6 +7370,25 @@ export declare const allTools: ({
         };
         required: string[];
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;

package/dist/tools/registry.js

@@ -40,6 +40,7 @@ import { refillTargetPlanToolDefinitions } from "./refill-target-plan.js";
 import { rowToolDefinitions } from "./rows.js";
 import { rubricToolDefinitions } from "./rubrics.js";
 import { schedulerFillCapacityToolDefinitions } from "./scheduler-fill-capacity.js";
+import { schedulerRunToolDefinitions } from "./scheduler-run.js";
 import { senderRoutingToolDefinitions } from "./sender-routing.js";
 import { senderToolDefinitions } from "./senders.js";
 import { sequencerToolDefinitions } from "./sequencer.js";
@@ -57,6 +58,7 @@ export const allTools = [
     ...refillPlanV2ToolDefinitions,
     ...refillTargetPlanToolDefinitions,
     ...schedulerFillCapacityToolDefinitions,
+    ...schedulerRunToolDefinitions,
     ...refillSendsToolDefinitions,
     ...refillSendsV2ToolDefinitions,
     ...setupEvergreenCampaignsToolDefinitions,

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

@@ -0,0 +1,27 @@
+type SchedulerRunAction = "run" | "status";
+type RunSchedulerSweepInput = {
+    workspaceId: string;
+    action?: SchedulerRunAction;
+};
+export declare const schedulerRunToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function runSchedulerSweep(input: RunSchedulerSweepInput): Promise<unknown>;
+export {};

package/dist/tools/scheduler-run.js

@@ -0,0 +1,45 @@
+import { getApi } from "../api.js";
+import { normalizeExplicitWorkspaceId, workspaceRequestOptions, } from "./workspace-context.js";
+async function postSchedulerRun(body, workspaceId) {
+    const api = getApi();
+    const requestOptions = workspaceRequestOptions(workspaceId);
+    return requestOptions
+        ? api.post("/api/v3/mcp/scheduler-run", body, requestOptions)
+        : api.post("/api/v3/mcp/scheduler-run", body);
+}
+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 returns a synchronous envelope with status ran, attached, backoff, window_closed_noop, or failed; retryAfterMs for backoff replays; and a receipt with cellsConsidered, cellsScheduled, cellsSkipped, cellsDeferred, deterministic skipReasons, and tablesFilteredForNoCapacity. 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: {
+                workspaceId: {
+                    type: "string",
+                    description: "Explicit request-scoped workspace id for scheduled/yolo refill automation. Pass this instead of switching the shared active workspace.",
+                },
+                action: {
+                    type: "string",
+                    enum: ["run", "status"],
+                    description: 'Use "run" to trigger a placement sweep now. Use "status" for a read-only view of the last on-demand run. Defaults to "run".',
+                },
+            },
+            required: ["workspaceId"],
+            additionalProperties: false,
+        },
+    },
+];
+export async function runSchedulerSweep(input) {
+    const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
+    if (!workspaceId) {
+        throw new Error("workspaceId is required for run_scheduler_sweep.");
+    }
+    const action = input.action ?? "run";
+    if (action !== "run" && action !== "status") {
+        throw new Error('action must be "run" or "status" for run_scheduler_sweep.');
+    }
+    return postSchedulerRun({
+        workspaceId,
+        action,
+    }, workspaceId);
+}

package/package.json

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

package/skills/refill-sends/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - mcp__sellable__refill_sends
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
+  - mcp__sellable__run_scheduler_sweep
   - mcp__sellable__refresh_paid_inmail_credits
   - mcp__sellable__get_subskill_asset
   - mcp__sellable__get_auth_status
@@ -114,10 +115,11 @@ or install-time workspace mapping. Pass `workspaceId` on every scheduled or
 `--yolo` refill tool call, including setup/read calls such as
 `refill_sends`, `get_refill_target_plan`, `list_senders`,
 `get_sender_routing`, `resolve_campaign_fill_route`,
-`get_campaign_refill_state`, `get_scheduler_fill_capacity`, and any later
-refill mutation covered by the packet. Missing `workspaceId` in scheduled or
-`--yolo` mode is a blocker; stop with `WORKSPACE_REQUIRED` instead of running
-against an implicit or guessed workspace.
+`get_campaign_refill_state`, `get_scheduler_fill_capacity`,
+`run_scheduler_sweep`, and any later refill mutation covered by the packet.
+Missing `workspaceId` in scheduled or `--yolo` mode is a blocker; stop with
+`WORKSPACE_REQUIRED` instead of running against an implicit or guessed
+workspace.
 
 Do not solve scheduled or `--yolo` workspace uncertainty by changing the shared
 active workspace. Manual interactive workspace switching remains a separate
@@ -269,6 +271,10 @@ need raw proof, call the read-only `get_scheduler_fill_capacity` query for the
 same sender/action/date; it tells the MCP how many cells the product scheduler
 will try to place and does not import, approve, schedule, refresh credits, or
 mutate.
+When the refill loop has ready rows and needs scheduler pickup now, use
+`run_scheduler_sweep` with the same explicit `workspaceId`; it can place cells
+within existing scheduler gates and returns the receipt, but it never sends or
+bypasses limits.
 If the target plan is complete by projected coverage, report that the selected
 target is already filled and no-op without asking for approval. If the ready
 buffer covers the projected gap, paid InMail credit facts are fresh for every

package/skills/refill-sends-workflow/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools:
   - mcp__sellable__get_subskill_asset
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
+  - mcp__sellable__run_scheduler_sweep
   - mcp__sellable__refresh_paid_inmail_credits
   - mcp__sellable__list_senders
   - mcp__sellable__get_sender_routing
@@ -67,11 +68,12 @@ request-scoped `workspaceId`. Pass that same `workspaceId` on every refill tool
 call in this workflow: `get_refill_target_plan`, `list_senders`,
 `get_sender_routing`, `resolve_campaign_fill_route`,
 `get_campaign_refill_state`, `get_scheduler_fill_capacity`,
-`refresh_paid_inmail_credits`, source import/readiness calls, preparation calls,
-approval calls, and campaign start calls. Missing `workspaceId` in scheduled or
-`--yolo` mode is a blocker; return or report `WORKSPACE_REQUIRED` instead of
-falling back to shared config state. Manual interactive workspace switching is
-diagnostic setup only and is not an automation control path.
+`run_scheduler_sweep`, `refresh_paid_inmail_credits`, source import/readiness
+calls, preparation calls, approval calls, and campaign start calls. Missing
+`workspaceId` in scheduled or `--yolo` mode is a blocker; return or report
+`WORKSPACE_REQUIRED` instead of falling back to shared config state. Manual
+interactive workspace switching is diagnostic setup only and is not an
+automation control path.
 
 Goal-mode continuation: a skill cannot create or invoke `/goal` by itself. When
 this workflow is already running inside an active Codex goal, keep that goal
@@ -186,6 +188,10 @@ files or memory.
    how many cells the product scheduler will try to place for that sender; it
    does not create rows, import, approve, schedule, refresh paid-InMail credits,
    or mutate thresholds.
+   When ready rows exist and the wait is for scheduler pickup, call
+   `run_scheduler_sweep` with the same explicit `workspaceId` to request the
+   product scheduler placement pass now and read its receipt. This may place
+   cells within existing gates, never sends messages, and never bypasses limits.
    If `status:"complete"`, report the target, selected dates, sent count,
    scheduled count, projected count, campaign ids, and no-op proof without
    asking for approval or mutating.