@sellable/mcp 0.1.570 → 0.1.572

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.570",
+  "version": "0.1.572",
   "type": "module",
   "description": "Sellable MCP server for Claude Code, Codex, and Hermes campaign workflows",
   "main": "dist/index.js",

package/skills/refill-sends/SKILL.md

@@ -223,13 +223,17 @@ Structured planner packet:
   campaign/sender/lane summary, skipped rungs, existing-row frontier proof, and
   any absolute `wait.deadlineAt`.
 - Preserve these coverage labels exactly: `Need to prepare`, `Goal`,
-  `Already sent`, `Scheduled`, `Ready and waiting to be scheduled`, and
-  `Still need`.
+  `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.
 - `target.globalActionQueue` is the only cross-sender yolo execution queue.
   Execute exactly one globally ranked primitive from
   `target.globalActionQueue[0]`, then rerun `get_refill_target_plan` with the
   same `workspaceId` before
   choosing another action.
+- When that primitive is `run_scheduler_sweep`, show `workspaceWide:true` and
+  its reason in the approval/yolo packet so the operator sees that the sweep
+  may schedule other eligible workspace cells on the approved date.
 - `manualAlternates` are not yolo actions. Threshold lowering and campaign
   creation are manual continuations only.
 
@@ -324,12 +328,16 @@ 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
 selected paid-InMail lane, but scheduled coverage is still short, keep the run
-open in a persistent read-only scheduler wait loop. Poll
-`get_refill_target_plan` every 60-120 seconds, or on the host's next continuation
-interval, until projected coverage fills the target, a concrete non-scheduler
-blocker appears, or Christian explicitly asks to stop or only receive a status
-report. Treat `awaiting_scheduler_after_ready_buffer` as an in-progress wait
-state, not a close-out condition.
+open in a persistent read-only scheduler wait loop. Honor the emitted wait
+metadata: reread `get_refill_target_plan` after about 30 seconds by default (or
+the action's explicit `rereadAfterMs`), never use a blind hard-coded sleep, and
+stop at the named bound using `receipt_deadline > unchanged_poll_bound >
+run_budget` precedence. A matching active/uncertain request key is never
+redispatched. Continue until projected coverage fills the target, a concrete
+non-scheduler blocker appears, a named bound stops the run, or Christian
+explicitly asks to stop or only receive a status report. Treat
+`awaiting_scheduler_after_ready_buffer` as an in-progress wait state, not a
+close-out condition.
 Wait actions are gates, not competing goals. When `wait_for_active_work` or
 `wait_for_scheduler` includes receipt `wait.deadlineAt`, honor that absolute
 deadline; if it is expired on this call, escalate to diagnostics with the

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

@@ -140,13 +140,17 @@ files or memory.
      campaign/sender/lane summary, skipped rungs, existing-row frontier proof,
      and any absolute `wait.deadlineAt`.
    - Preserve these coverage labels exactly: `Need to prepare`, `Goal`,
-     `Already sent`, `Scheduled`, `Ready and waiting to be scheduled`, and
-     `Still need`.
+     `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.
    - `target.globalActionQueue` is the only cross-sender yolo execution queue.
      execute exactly one globally ranked primitive from
      `target.globalActionQueue[0]`, then rerun `get_refill_target_plan` with
      the same `workspaceId` before
      choosing another action.
+   - When that primitive is `run_scheduler_sweep`, show `workspaceWide:true`
+     and its reason in the approval/yolo packet so the operator sees that the
+     sweep may schedule other eligible workspace cells on the approved date.
    - `nextActions[0]` is the current sender's smallest safe primitive.
    - `manualAlternates` are not yolo actions. Threshold lowering and campaign
      creation are manual continuations only.

package/skills/research/config.json

@@ -0,0 +1,9 @@
+{
+  "parallelMode": "wide",
+  "agentCount": 6,
+  "maxToolCallsPerAgent": 2,
+  "senderMaxAgents": 2,
+  "senderMaxToolCallsPerAgent": 3,
+  "progressMode": true,
+  "debugMode": true
+}