@sellable/mcp 0.1.540 → 0.1.542

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

@@ -14,6 +14,12 @@ export type PaidInmailCreditRefreshOptions = {
     maxStalenessSeconds?: number | null;
     paidInmailCreditsMaxStalenessSeconds?: number | null;
 };
+export type PaidInmailRefreshReceiptClassification = {
+    usableCurrentFacts: boolean;
+    status: string;
+    error: string | null;
+    refreshed: boolean;
+};
 export type YoloPrimitiveExecution = {
     enabled: true;
     status: "no_action" | "read_only_reread" | "executed_and_reread" | "refused" | "skipped_after_paid_refresh";
@@ -135,6 +141,7 @@ export declare function userAddedRowsLimitPayloadFromError(error: unknown): User
 export declare function sourceImportInProgressPayloadFromError(error: unknown): SourceImportInProgressPayload | null;
 export declare function paidRefreshActionFrom(value: unknown): PaidInmailRefreshAction | null;
 export declare function collectPaidInmailRefreshActions(plan: unknown): PaidInmailRefreshAction[];
+export declare function classifyPaidInmailRefreshReceipt(value: unknown): PaidInmailRefreshReceiptClassification;
 export declare function firstGlobalAction(plan: unknown): Record<string, unknown> | null;
 export declare function actionIds(action: Record<string, unknown>): Record<string, unknown>;
 export declare function actionToolInput(action: Record<string, unknown>): Record<string, unknown>;

package/dist/tools/refill-executors.js

@@ -10,6 +10,11 @@ const PAID_INMAIL_REFRESH_RETRY_DELAY_MS = Number(process.env.SELLABLE_MCP_PAID_
 const SIGNAL_DISCOVERY_MIN_REFILL_POSTS = 3;
 const SIGNAL_DISCOVERY_MAX_REFILL_POSTS = 10;
 const SIGNAL_DISCOVERY_TARGET_ROWS_PER_POST = 150;
+const USABLE_PAID_INMAIL_REFRESH_RECEIPT_STATUSES = new Set([
+    "fresh",
+    "refreshed",
+    "below_threshold",
+]);
 export function normalizeStrings(values) {
     if (!Array.isArray(values))
         return [];
@@ -206,6 +211,23 @@ export function collectPaidInmailRefreshActions(plan) {
         add(action);
     return [...bySender.values()];
 }
+export function classifyPaidInmailRefreshReceipt(value) {
+    const response = recordValue(value);
+    const nestedReceipt = recordValue(response?.receipt);
+    const status = stringValue(nestedReceipt?.status) ??
+        stringValue(response?.status) ??
+        (response?.refreshed === true ? "refreshed" : "not_refreshed");
+    const refreshed = response?.refreshed === true || nestedReceipt?.refreshed === true;
+    const usableCurrentFacts = refreshed || USABLE_PAID_INMAIL_REFRESH_RECEIPT_STATUSES.has(status);
+    return {
+        usableCurrentFacts,
+        status,
+        refreshed,
+        error: stringValue(response?.error) ??
+            stringValue(nestedReceipt?.error) ??
+            (usableCurrentFacts ? null : "paid InMail credit refresh did not return usable current facts"),
+    };
+}
 export function firstGlobalAction(plan) {
     const root = recordValue(plan);
     const target = recordValue(root?.target);
@@ -659,7 +681,7 @@ export async function executeStartCampaignPrimitive(params) {
         (params.authority.laneChainCampaignIds.includes(campaignId) ||
             authorizedByPinnedCampaign)) {
         try {
-            const result = await startCampaign(campaignId);
+            const result = await startCampaign(campaignId, params.workspaceId);
             return {
                 executed: true,
                 type: "start_paused_campaign",

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

@@ -6,9 +6,6 @@ type RefillSendsV2Input = {
     approvalMode?: "approve" | "mark_ready";
     senderIds?: string[];
     intent?: "auto" | "evergreen" | "plain" | "active";
-    targetDate?: string | null;
-    untilDate?: string | null;
-    horizonSendDays?: number | null;
 };
 export declare const refillSendsV2ToolDefinitions: {
     name: string;
@@ -47,22 +44,6 @@ export declare const refillSendsV2ToolDefinitions: {
                 type: string;
                 enum: string[];
             };
-            targetDate: {
-                type: string;
-                pattern: string;
-                description: string;
-            };
-            untilDate: {
-                type: string;
-                pattern: string;
-                description: string;
-            };
-            horizonSendDays: {
-                type: string;
-                minimum: number;
-                maximum: number;
-                description: string;
-            };
         };
         required: string[];
         additionalProperties: boolean;

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

@@ -18,7 +18,7 @@ const BOUNDED_AUTHORITY = "Within the refill run, bounded approvals, preparation
 export const refillSendsV2ToolDefinitions = [
     {
         name: "refill_sends_v2",
-        description: "Execute the refill sends v2 loop with run-record fencing, packet re-planning, shared refill executors, and resumable dry-run/real-run modes. Date selectors match refill_sends: targetDate is one exact sender-local date, untilDate is inclusive, horizonSendDays is the next N sender-local send days, with precedence targetDate > untilDate > horizonSendDays > default scheduler-forward planning.",
+        description: "Execute the refill sends v2 loop with run-record fencing, packet re-planning, shared refill executors, and resumable dry-run/real-run modes.",
         inputSchema: {
             type: "object",
             properties: {
@@ -51,22 +51,6 @@ export const refillSendsV2ToolDefinitions = [
                     type: "string",
                     enum: ["auto", "evergreen", "plain", "active"],
                 },
-                targetDate: {
-                    type: "string",
-                    pattern: "^\\d{4}-\\d{2}-\\d{2}$",
-                    description: "Optional one exact sender-local date (YYYY-MM-DD) to refill.",
-                },
-                untilDate: {
-                    type: "string",
-                    pattern: "^\\d{4}-\\d{2}-\\d{2}$",
-                    description: "Optional inclusive sender-local through-date (YYYY-MM-DD) to refill.",
-                },
-                horizonSendDays: {
-                    type: "number",
-                    minimum: 1,
-                    maximum: 7,
-                    description: "Optional explicit next N sender-local send days to refill.",
-                },
             },
             required: ["workspaceId"],
             additionalProperties: false,
@@ -115,9 +99,6 @@ export async function refillSendsV2Command(input) {
             workspaceId,
             intent: input.intent,
             senderIds: input.senderIds,
-            targetDate: input.targetDate,
-            untilDate: input.untilDate,
-            horizonSendDays: input.horizonSendDays,
             journal: true,
         });
         return {
@@ -132,9 +113,6 @@ export async function refillSendsV2Command(input) {
         workspaceId,
         intent: input.intent,
         senderIds: input.senderIds,
-        targetDate: input.targetDate,
-        untilDate: input.untilDate,
-        horizonSendDays: input.horizonSendDays,
         approvalMode: input.approvalMode ?? "approve",
         resume: resumeHandle(input),
     }, {
@@ -151,9 +129,6 @@ export async function refillSendsV2Command(input) {
             workspaceId: planInput.workspaceId,
             intent: planInput.intent,
             senderIds: planInput.senderIds,
-            targetDate: planInput.targetDate,
-            untilDate: planInput.untilDate,
-            horizonSendDays: planInput.horizonSendDays,
             runState: planInput.runState,
             journal: planInput.journal,
         }),
@@ -178,11 +153,7 @@ export async function refillSendsV2Command(input) {
         localState: {
             writeRefillWorkspaceState,
         },
-        requestSchedulerRun: (workspaceId, options) => runSchedulerSweep({
-            workspaceId,
-            action: "run",
-            targetDate: options?.targetDate,
-        }),
+        requestSchedulerRun: (workspaceId) => runSchedulerSweep({ workspaceId, action: "run" }),
     });
     return {
         ...(await maybeAddLostFenceGuidance(result, { ...input, workspaceId })),

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

@@ -292,6 +292,8 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
             attempts?: number;
             error: string;
             errors?: string[];
+            receiptStatus?: string;
+            receipt?: unknown;
         }[];
         refreshReceipts: {
             senderId: string;
@@ -301,6 +303,8 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
             approvalSource: string;
             approvalPacket: PaidInmailRefreshApprovalPacket;
             receipt: import("./senders.js").RefreshPaidInmailCreditsResponse;
+            receiptStatus: string;
+            usableCurrentFacts: boolean;
         }[];
         attemptedSenderIds: string[];
         targetPlanReread: boolean;
@@ -309,6 +313,14 @@ export declare function executeRefillSendsCommand(input?: RefillSendsCommandInpu
         note: string;
     };
     yoloExecution: {
+        enabled: false;
+        status: "not_run_without_yolo";
+        selectedAction: null;
+        targetPlanReread: false;
+        result?: undefined;
+        refusalReason?: undefined;
+        postActionFirstAction?: undefined;
+    } | {
         enabled: true;
         status: "skipped_after_paid_refresh";
         selectedAction: null;

package/dist/tools/refill-sends.js

@@ -1,18 +1,14 @@
-import { actionIds, collectPaidInmailRefreshActions, executeOneYoloPrimitive, firstGlobalAction, normalizeStrings, numberValue, recordValue, refreshPaidInmailCreditsWithRetry, stringValue, } from "./refill-executors.js";
+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 DEFAULT_SCHEDULER_FORWARD_HOURS = 48;
 const MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
 function normalizeHorizonSendDays(value) {
-    if (value === undefined)
+    if (value === undefined || value === null)
         return null;
-    if (typeof value !== "number" ||
-        !Number.isInteger(value) ||
-        value < 1 ||
-        value > 7) {
-        throw new Error("horizonSendDays must be an integer between 1 and 7.");
-    }
-    return value;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    return Math.max(1, Math.min(7, Math.floor(value)));
 }
 function normalizeUntilDate(value) {
     if (value === undefined || value === null || value === "")
@@ -95,7 +91,7 @@ export const refillSendsToolDefinitions = [
                     type: "number",
                     minimum: 1,
                     maximum: 7,
-                    description: "Compatibility override for explicit next N sender-local send days. Omit for the default scheduler-forward 48-hour target window.",
+                    description: "Compatibility override for an explicit sender-local send-day horizon. Omit for the default scheduler-forward 48-hour target window.",
                 },
                 untilDate: {
                     type: "string",
@@ -188,7 +184,7 @@ export function refillSendsCommand(input = {}) {
                     horizonHours: horizonSendDays === null ? DEFAULT_SCHEDULER_FORWARD_HOURS : null,
                     description: horizonSendDays === null
                         ? "Fill the default scheduler-forward 48-hour target window."
-                        : `Fill the next ${horizonSendDays} sender-local send days.`,
+                        : "Fill the explicit compatibility horizon by sender-local send days.",
                 },
         approvalMode,
         campaignId: input.campaignId ?? null,
@@ -235,7 +231,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 --yolo, this tool automatically maintains a run-local refreshedPaidInmailSenderIds set: when the first target plan returns refresh_paid_inmail_credits candidates for selected paid-InMail lanes, it refreshes each exact sender at most once, reruns get_refill_target_plan, and returns 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/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.",
@@ -379,7 +375,11 @@ export async function executeRefillSendsCommand(input = {}) {
         ? { ...input, workspaceId: workspaceContext.context.workspaceId }
         : input;
     const command = refillSendsCommand(scopedInput);
-    if (!yolo) {
+    const workspaceId = workspaceContext && workspaceContext.ok
+        ? workspaceContext.context.workspaceId
+        : normalizeExplicitWorkspaceId(scopedInput.workspaceId);
+    const canRefreshPaidInmailFacts = yolo || executionMode === "scheduled" || Boolean(workspaceId);
+    if (!canRefreshPaidInmailFacts) {
         return {
             ...command,
             autoPaidInmailRefresh: {
@@ -387,7 +387,7 @@ export async function executeRefillSendsCommand(input = {}) {
                 status: "not_run_without_yolo",
                 refreshedPaidInmailSenderIds: [],
                 failedPaidInmailRefreshes: [],
-                note: "Automatic paid InMail credit refresh only runs for --yolo refill_sends calls.",
+                note: "Automatic paid InMail credit refresh requires --yolo, scheduled mode, or an explicit workspaceId so the request can refresh exact sender facts safely.",
             },
             yoloExecution: {
                 enabled: false,
@@ -397,9 +397,6 @@ export async function executeRefillSendsCommand(input = {}) {
             },
         };
     }
-    const workspaceId = workspaceContext && workspaceContext.ok
-        ? workspaceContext.context.workspaceId
-        : normalizeExplicitWorkspaceId(scopedInput.workspaceId);
     const targetPlanInput = targetPlanInputFor(scopedInput);
     const targetPlanBeforePaidRefresh = await getRefillTargetPlan(targetPlanInput);
     const refreshActions = collectPaidInmailRefreshActions(targetPlanBeforePaidRefresh);
@@ -425,7 +422,7 @@ export async function executeRefillSendsCommand(input = {}) {
         }
         const refreshResult = await refreshPaidInmailCreditsWithRetry(action.senderId, workspaceId, paidRefreshOptionsFromApprovalPacket(approvalPacket));
         if (refreshResult.receipt) {
-            refreshedPaidInmailSenderIds.push(action.senderId);
+            const classification = classifyPaidInmailRefreshReceipt(refreshResult.receipt);
             refreshReceipts.push({
                 senderId: action.senderId,
                 actionKey: action.actionKey ?? null,
@@ -434,7 +431,23 @@ export async function executeRefillSendsCommand(input = {}) {
                 approvalSource: "explicit_yolo_flag",
                 approvalPacket,
                 receipt: refreshResult.receipt,
+                receiptStatus: classification.status,
+                usableCurrentFacts: classification.usableCurrentFacts,
             });
+            if (classification.usableCurrentFacts) {
+                refreshedPaidInmailSenderIds.push(action.senderId);
+            }
+            else {
+                failedPaidInmailRefreshes.push({
+                    senderId: action.senderId,
+                    attempts: refreshResult.attempts,
+                    error: classification.error ??
+                        "paid InMail credit refresh did not return usable current facts",
+                    errors: refreshResult.errors,
+                    receiptStatus: classification.status,
+                    receipt: refreshResult.receipt,
+                });
+            }
         }
         else {
             failedPaidInmailRefreshes.push({
@@ -449,8 +462,8 @@ export async function executeRefillSendsCommand(input = {}) {
     const targetPlan = refreshActions.length > 0
         ? await getRefillTargetPlan(targetPlanInput)
         : targetPlanBeforePaidRefresh;
-    const selectedAction = refreshActions.length > 0 ? null : firstGlobalAction(targetPlan);
-    const primitiveAttempt = refreshActions.length > 0
+    const selectedAction = yolo && refreshActions.length === 0 ? firstGlobalAction(targetPlan) : null;
+    const primitiveAttempt = !yolo || refreshActions.length > 0
         ? null
         : await executeOneYoloPrimitive(selectedAction, workspaceId ?? undefined);
     const shouldRereadAfterPrimitive = primitiveAttempt?.status === "executed_and_reread" ||
@@ -463,7 +476,9 @@ export async function executeRefillSendsCommand(input = {}) {
         ...command,
         targetPlan: finalTargetPlan,
         targetPlanBeforePaidRefresh: refreshActions.length > 0 ? targetPlanBeforePaidRefresh : null,
-        targetPlanBeforeYoloPrimitive: refreshActions.length === 0 && postActionTargetPlan ? targetPlan : null,
+        targetPlanBeforeYoloPrimitive: yolo && refreshActions.length === 0 && postActionTargetPlan
+            ? targetPlan
+            : null,
         autoPaidInmailRefresh: {
             enabled: true,
             status: refreshActions.length === 0
@@ -482,23 +497,30 @@ export async function executeRefillSendsCommand(input = {}) {
                 ? "refill_sends refreshed stale paid InMail credit facts internally with bounded retries, once per sender, then returned the post-refresh targetPlan."
                 : "No stale or missing paid InMail credit refresh candidates were present in the initial target plan.",
         },
-        yoloExecution: refreshActions.length > 0
+        yoloExecution: !yolo
             ? {
-                enabled: true,
-                status: "skipped_after_paid_refresh",
+                enabled: false,
+                status: "not_run_without_yolo",
                 selectedAction: null,
-                targetPlanReread: true,
+                targetPlanReread: false,
             }
-            : {
-                enabled: true,
-                status: primitiveAttempt?.status ?? "no_action",
-                selectedAction,
-                result: primitiveAttempt?.result,
-                targetPlanReread: shouldRereadAfterPrimitive,
-                refusalReason: primitiveAttempt?.refusalReason,
-                postActionFirstAction: postActionTargetPlan
-                    ? firstGlobalAction(postActionTargetPlan)
-                    : null,
-            },
+            : refreshActions.length > 0
+                ? {
+                    enabled: true,
+                    status: "skipped_after_paid_refresh",
+                    selectedAction: null,
+                    targetPlanReread: true,
+                }
+                : {
+                    enabled: true,
+                    status: primitiveAttempt?.status ?? "no_action",
+                    selectedAction,
+                    result: primitiveAttempt?.result,
+                    targetPlanReread: shouldRereadAfterPrimitive,
+                    refusalReason: primitiveAttempt?.refusalReason,
+                    postActionFirstAction: postActionTargetPlan
+                        ? firstGlobalAction(postActionTargetPlan)
+                        : null,
+                },
     };
 }

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

@@ -1026,16 +1026,6 @@ function sanitizeRefillTargetPlanResult(result) {
         mcpSanitizedRefillLanes: true,
     };
 }
-function stripInternalTargetDateKeys(value) {
-    if (Array.isArray(value)) {
-        return value.map((item) => stripInternalTargetDateKeys(item));
-    }
-    if (!isRecord(value))
-        return value;
-    return Object.fromEntries(Object.entries(value)
-        .filter(([key]) => key !== "targetDateKey")
-        .map(([key, nested]) => [key, stripInternalTargetDateKeys(nested)]));
-}
 export const refillTargetPlanToolDefinitions = [
     {
         name: "get_refill_target_plan",
@@ -1052,7 +1042,7 @@ export const refillTargetPlanToolDefinitions = [
                     type: "number",
                     minimum: 1,
                     maximum: 7,
-                    description: "Compatibility override for explicit next N sender-local send days. Omit for the default scheduler-forward 48-hour target window; no-send days are skipped while choosing the requested send days.",
+                    description: "Compatibility override for explicit sender-local send-day horizon planning. Omit for the default scheduler-forward 48-hour target window; no-send days contribute zero target.",
                 },
                 untilDate: {
                     type: "string",
@@ -1062,7 +1052,7 @@ export const refillTargetPlanToolDefinitions = [
                 targetDate: {
                     type: "string",
                     pattern: "^\\d{4}-\\d{2}-\\d{2}$",
-                    description: "Optional one exact sender-local date (YYYY-MM-DD) to fill. Distinct from untilDate: targetDate asks how many scheduler-fillable slots exist on only this date.",
+                    description: "Optional exact sender-local YYYY-MM-DD date to fill. Distinct from untilDate: targetDate asks how many scheduler-fillable slots exist on only this date.",
                 },
                 campaignId: {
                     type: "string",
@@ -1112,14 +1102,11 @@ export const refillTargetPlanToolDefinitions = [
 ];
 export async function getRefillTargetPlan(input = {}) {
     const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
-    const targetDate = input.targetDate;
-    const untilDate = targetDate ? undefined : input.untilDate;
-    const horizonSendDays = targetDate || untilDate ? undefined : input.horizonSendDays;
     const result = await postRefillTargetPlan({
         intent: input.intent,
-        horizonSendDays,
-        untilDate,
-        targetDate,
+        horizonSendDays: input.horizonSendDays,
+        untilDate: input.untilDate,
+        targetDate: input.targetDate,
         campaignId: input.campaignId,
         tableId: input.tableId,
         senderIds: input.senderIds,
@@ -1130,7 +1117,7 @@ export async function getRefillTargetPlan(input = {}) {
         paidInmailCreditsMaxStalenessSeconds: MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS,
         ...(workspaceId ? { workspaceId } : {}),
     }, workspaceId ?? undefined);
-    const sanitized = stripInternalTargetDateKeys(sanitizeRefillTargetPlanResult(result));
+    const sanitized = sanitizeRefillTargetPlanResult(result);
     if (!workspaceId || !isRecord(sanitized))
         return sanitized;
     return {

package/dist/tools/refresh-sender-engagement.d.ts

@@ -0,0 +1,50 @@
+export type RefreshSenderEngagementInput = {
+    workspaceId?: string;
+    mode?: "dry_run" | "apply";
+    senderId?: string;
+    tableId?: string;
+    maxPosts?: number;
+    maxEngagerPages?: number;
+    dryRunFingerprint?: string;
+};
+export declare const refreshSenderEngagementToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            senderId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+            maxPosts: {
+                type: string;
+                description: string;
+            };
+            maxEngagerPages: {
+                type: string;
+                description: string;
+            };
+            dryRunFingerprint: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function refreshSenderEngagementCommand(input: RefreshSenderEngagementInput): Promise<unknown>;

package/dist/tools/refresh-sender-engagement.js

@@ -0,0 +1,60 @@
+import { getApi } from "../api.js";
+import { createWorkspaceContext } from "./workspace-context.js";
+export const refreshSenderEngagementToolDefinitions = [
+    {
+        name: "refresh_sender_engagement",
+        description: "Refresh one sender-owned Post Engagers campaign through the product-native CampaignTrackedPost path. Dry-run first returns a human-reviewable receipt; apply requires that dry-run fingerprint and never sends, schedules, approves, prepares messages, launches campaigns, or mutates shared Signal Discovery lanes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Explicit request-scoped workspace id.",
+                },
+                mode: {
+                    type: "string",
+                    enum: ["dry_run", "apply"],
+                    description: "dry_run is read-only and returns an approval packet; apply requires dryRunFingerprint.",
+                },
+                senderId: {
+                    type: "string",
+                    description: "Exactly one Sellable sender id to refresh.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional campaign table id for disambiguating the sender-owned Post Engagers lane.",
+                },
+                maxPosts: {
+                    type: "number",
+                    description: "Maximum tracked/sender-authored posts to refresh.",
+                },
+                maxEngagerPages: {
+                    type: "number",
+                    description: "Maximum provider pages per engager source.",
+                },
+                dryRunFingerprint: {
+                    type: "string",
+                    description: "Required for apply; returned by the matching dry_run receipt.",
+                },
+            },
+            required: ["workspaceId", "mode", "senderId"],
+            additionalProperties: false,
+        },
+    },
+];
+function compactBody(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+export async function refreshSenderEngagementCommand(input) {
+    const workspace = createWorkspaceContext({
+        workspaceId: input.workspaceId,
+        executionMode: input.mode === "apply" ? "yolo" : "manual",
+        toolName: "refresh_sender_engagement",
+    });
+    if (!workspace.ok)
+        return workspace;
+    return getApi().post("/api/v3/mcp/refresh-sender-engagement", compactBody({
+        ...input,
+        workspaceId: workspace.context.workspaceId,
+    }), workspace.context.requestOptions);
+}