@sellable/mcp 0.1.557 → 0.1.559

package/dist/refill-run-loop.js

@@ -59,6 +59,16 @@ const SCHEDULER_RUN_NEXT_ACTIONS = new Set([
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function planScopeInput(input) {
+    return {
+        ...(input.targetDate ? { targetDate: input.targetDate } : {}),
+        ...(input.untilDate ? { untilDate: input.untilDate } : {}),
+        ...(input.horizonSendDays !== undefined
+            ? { horizonSendDays: input.horizonSendDays }
+            : {}),
+        ...(input.scopeHash ? { scopeHash: input.scopeHash } : {}),
+    };
+}
 function stringValue(value) {
     return typeof value === "string" && value.trim() ? value.trim() : null;
 }
@@ -256,10 +266,8 @@ function sanitizeSchedulerRunReceipt(raw) {
         const prefilteredCells = numberValue(rawReceipt.prefilteredCells) ?? 0;
         const tablesFilteredForSenderMismatch = numberValue(rawReceipt.tablesFilteredForSenderMismatch) ?? 0;
         dominantSkipReason = dominantSchedulerRunSkipReason(skipReasons);
-        dominantPrefilterReason =
-            dominantSchedulerRunCountReason(prefilterReasons);
-        dominantDeferredReason =
-            dominantSchedulerRunSkipReason(deferredReasons);
+        dominantPrefilterReason = dominantSchedulerRunCountReason(prefilterReasons);
+        dominantDeferredReason = dominantSchedulerRunSkipReason(deferredReasons);
         recommendedNextAction = schedulerRunRecommendedAction({
             rawAction: stringValue(rawReceipt.nextAction),
             readyCellsFound,
@@ -353,11 +361,17 @@ function actionSenderId(action) {
 }
 function fingerprintFromPlan(plan) {
     const packet = recordValue(plan.packet) ?? {};
+    const targetShapeRevision = stringValue(packet.targetShapeRevision) ??
+        stringValue(packet.targetRevision) ??
+        stringValue(plan.targetShapeRevision) ??
+        stringValue(plan.targetRevision);
     return {
-        planRevision: stringValue(plan.planRevision),
+        // Evergreen packets carry their own semantic plan revision. Regular
+        // active-campaign packets intentionally do not, so their immutable target
+        // shape is the durable planning revision for fencing and recovery.
+        planRevision: stringValue(plan.planRevision) ?? targetShapeRevision,
         stateRevision: stringValue(plan.stateRevision) ?? stringValue(packet.stateRevision),
-        targetShapeRevision: stringValue(packet.targetShapeRevision) ??
-            stringValue(packet.targetRevision),
+        targetShapeRevision,
     };
 }
 function fingerprintChanged(expected, actual) {
@@ -429,6 +443,43 @@ function normalizeDoneReason(value) {
 function runStateProgress(ctx) {
     return recordValue(ctx.runState.progress) ?? {};
 }
+function prepCircuitFrom(value) {
+    const root = recordValue(value);
+    const result = recordValue(root?.result);
+    const progress = recordValue(root?.progress);
+    return (recordValue(root?.circuit) ??
+        recordValue(result?.circuit) ??
+        recordValue(progress?.circuit) ??
+        null);
+}
+function openCircuitWaits(circuit, now) {
+    if (stringValue(circuit?.state) !== "open")
+        return false;
+    const nextProbeAt = stringValue(circuit?.nextProbeAt);
+    return Boolean(nextProbeAt && Date.parse(nextProbeAt) > now.getTime());
+}
+function activePreparationScopeSatisfied(plan, action) {
+    const packet = recordValue(plan.packet) ?? plan;
+    const target = recordValue(packet.target) ?? recordValue(plan.target) ?? {};
+    const senderId = actionSenderId(action);
+    const toolInput = actionToolInput(action);
+    const targetDate = stringValue(toolInput.targetDate);
+    const refillLaneKey = stringValue(toolInput.refillLaneKey);
+    const senderPlans = arrayValue(target.senderRefillPlans).filter(isRecord);
+    const ledgers = senderPlans
+        .filter((senderPlan) => !senderId || stringValue(senderPlan.senderId) === senderId)
+        .flatMap((senderPlan) => arrayValue(senderPlan.laneLedgers).filter(isRecord));
+    const matching = ledgers.filter((ledger) => (!senderId || stringValue(ledger.senderId) === senderId) &&
+        (!targetDate || stringValue(ledger.targetDate) === targetDate) &&
+        (!refillLaneKey || stringValue(ledger.refillLaneKey) === refillLaneKey));
+    return (matching.length > 0 &&
+        matching.every((ledger) => {
+            const checks = recordValue(ledger.identityChecks);
+            return (numberValue(ledger.initialAllocatablePrepDeficit) === 0 &&
+                checks != null &&
+                Object.values(checks).every((value) => value === true));
+        }));
+}
 function mergeProgress(ctx, updates) {
     return {
         ...runStateProgress(ctx),
@@ -672,14 +723,28 @@ async function createJournal(input, deps, runId) {
 }
 async function startOrResume(input, deps) {
     const initialRunState = buildRunStateFromLocalHints(input.workspaceId);
+    const scopedInitialRunState = input.scope
+        ? {
+            ...initialRunState,
+            scope: input.scope,
+            scopeHash: input.scopeHash,
+            approval: input.approval,
+        }
+        : initialRunState;
     const started = await deps.runClient.startRefillRunRemote({
         workspaceId: input.workspaceId,
-        config: {
-            intent: input.intent ?? "auto",
-            senderIds: input.senderIds,
-            approvalMode: input.approvalMode ?? "approve",
-        },
-        runState: initialRunState,
+        config: input.scope
+            ? {
+                scope: input.scope,
+                scopeHash: input.scopeHash,
+                approval: input.approval,
+            }
+            : {
+                intent: input.intent ?? "auto",
+                senderIds: input.senderIds,
+                approvalMode: input.approvalMode ?? "approve",
+            },
+        runState: scopedInitialRunState,
         resume: input.resume,
     });
     if (isLeaseLost(started)) {
@@ -712,7 +777,7 @@ async function startOrResume(input, deps) {
     const gate = (stringValue(result.gate) ?? "g0_bootstrap");
     const gateSeq = numberValue(result.gateSeq) ?? 0;
     const runState = recordValue(result.runState) ??
-        recordValue(initialRunState) ??
+        recordValue(scopedInitialRunState) ??
         {
             version: 1,
             senderCursors: [],
@@ -755,6 +820,7 @@ async function gateBootstrap(input, deps, ctx) {
         senderIds: input.senderIds,
         runState: ctx.runState,
         journal: false,
+        ...planScopeInput(input),
     });
     const paidCredit = arrayValue(recordValue(plan.bootstrap)?.paidCredit).filter(isRecord);
     const refreshedSenderIds = new Set(arrayValue(recordValue(ctx.runState.creditTrust)?.senderIds)
@@ -901,6 +967,7 @@ async function gatePlan(input, deps, ctx) {
         senderIds: input.senderIds,
         runState: ctx.runState,
         journal: false,
+        ...planScopeInput(input),
     });
     if (plan.blocker === "workspace_access") {
         return {
@@ -960,6 +1027,17 @@ async function gatePlan(input, deps, ctx) {
         fallbackSummary: line.fallbackSummary,
     }));
     const fingerprint = fingerprintFromPlan(plan);
+    const persistedCircuit = recordValue(runStateProgress(ctx).prepCircuit);
+    if (stringValue(action.type) === "prepare_messages" &&
+        openCircuitWaits(persistedCircuit, deps.now?.() ?? new Date())) {
+        const heartbeat = await heartbeatAndContinue(input, deps, ctx);
+        if (heartbeat.status !== "in_progress")
+            return heartbeat;
+        return {
+            ...heartbeat,
+            guidance: `Preparation circuit remains open until ${String(persistedCircuit?.nextProbeAt)}; re-invoke with this handle after the probe deadline.`,
+        };
+    }
     const noProgress = nextNoProgressState(ctx, plan, action);
     if (noProgress.repeatCount >= 3) {
         return completeTerminal(input, deps, ctx, "blocked", {
@@ -970,10 +1048,17 @@ async function gatePlan(input, deps, ctx) {
             guidance: "The same refill rung repeated three times with no coverage, frontier, or lane movement.",
         });
     }
+    const circuitProgress = stringValue(action.type) === "prepare_messages" &&
+        stringValue(persistedCircuit?.state) === "open"
+        ? { ...persistedCircuit, state: "half_open" }
+        : persistedCircuit;
     const nextRunState = mergeRunState(ctx.runState, {
         lastPlan: fingerprint,
         headAction: action,
-        progress: mergeProgress(ctx, { noProgress }),
+        progress: mergeProgress(ctx, {
+            noProgress,
+            ...(circuitProgress ? { prepCircuit: circuitProgress } : {}),
+        }),
     });
     const advanced = await deps.runClient.advanceRefillRunGateRemote({
         workspaceId: input.workspaceId,
@@ -1010,6 +1095,7 @@ async function verifyRecoveryPoint(input, deps, ctx) {
         senderIds: input.senderIds,
         runState: ctx.runState,
         journal: false,
+        ...planScopeInput(input),
     });
     const changed = fingerprintChanged(expected, fingerprintFromPlan(fresh));
     if (changed.length > 0) {
@@ -1079,6 +1165,9 @@ async function gateExecute(input, deps, ctx) {
         dispatchKey: stringValue(action.type),
         evergreenRung: stringValue(action.evergreenRung),
         sideEffectClass: stringValue(action.sideEffectClass),
+        scopeHash: input.scopeHash ?? null,
+        expectedTargetsHash: stringValue(input.scope?.expectedTargetsHash) ?? null,
+        dateSelector: recordValue(input.scope?.dateSelector),
     };
     const plannedResult = await deps.runClient.recordRunPlanned({
         workspaceId: input.workspaceId,
@@ -1172,6 +1261,12 @@ async function advanceBackToPlan(input, deps, ctx, runStateUpdates = {}) {
 async function verifyPrepareAction(input, deps, ctx, action, budgets) {
     const getStatus = deps.executors.getPrepareCampaignMessagesStatus;
     const jobId = activeJobIdFromOutcome(ctx.runState.lastOutcome);
+    const executionCircuit = prepCircuitFrom(ctx.runState.lastOutcome);
+    if (!jobId && executionCircuit) {
+        return advanceBackToPlan(input, deps, ctx, {
+            progress: mergeProgress(ctx, { prepCircuit: executionCircuit }),
+        });
+    }
     if (!getStatus || !jobId) {
         return {
             status: "in_progress",
@@ -1211,6 +1306,58 @@ async function verifyPrepareAction(input, deps, ctx, action, budgets) {
                 }),
             });
         }
+        if (ownJob &&
+            !isTerminalJobStatus(latestStatus) &&
+            deps.executors.stopSatisfiedPrepareCampaignMessages) {
+            const fresh = await deps.readPlan({
+                workspaceId: input.workspaceId,
+                intent: input.intent,
+                senderIds: input.senderIds,
+                runState: ctx.runState,
+                journal: false,
+                ...planScopeInput(input),
+            });
+            ctx.plan = fresh;
+            if (activePreparationScopeSatisfied(fresh, action)) {
+                const plannedStop = await deps.runClient.recordRunPlanned({
+                    workspaceId: input.workspaceId,
+                    runId: ctx.runId,
+                    fence: ctx.fence,
+                    gate: ctx.gate,
+                    gateSeq: ctx.gateSeq,
+                    planned: {
+                        toolName: "stop_satisfied_campaign_message_preparation",
+                        toolInput: { jobId },
+                        dispatchKey: `stop_satisfied:${jobId}`,
+                        sideEffectClass: "message_preparation_stop",
+                        scopeHash: input.scopeHash ?? null,
+                    },
+                });
+                if (isLeaseLost(plannedStop))
+                    return leaseLostResult(ctx);
+                const stopEventId = stringValue(recordValue(plannedStop)?.eventId) ??
+                    `${ctx.runId}:${ctx.gateSeq}:stop`;
+                const stopReceipt = await deps.executors.stopSatisfiedPrepareCampaignMessages({
+                    workspaceId: input.workspaceId,
+                    jobId,
+                    expectedUpdatedAt: stringValue(statusRecord.updatedAt) ?? undefined,
+                });
+                await deps.runClient.recordRunOutcome({
+                    workspaceId: input.workspaceId,
+                    runId: ctx.runId,
+                    fence: ctx.fence,
+                    eventId: stopEventId,
+                    did: { jobId },
+                    outcome: stopReceipt,
+                });
+                return advanceBackToPlan(input, deps, ctx, {
+                    progress: mergeProgress(ctx, {
+                        prepStopReceipt: stopReceipt,
+                        prepStoppedAt: (deps.now?.() ?? new Date()).toISOString(),
+                    }),
+                });
+            }
+        }
         if (isTerminalJobStatus(latestStatus)) {
             const preparedCount = preparedCountFromStatus(latestStatus);
             const checkedRows = checkedRowsFromStatus(latestStatus);
@@ -1278,6 +1425,7 @@ async function verifyReadOnlyWait(input, deps, ctx, budgets, waitKind) {
             senderIds: input.senderIds,
             runState: ctx.runState,
             journal: false,
+            ...planScopeInput(input),
         });
         ctx.plan = fresh;
         const doneReason = doneReasonFromPlan(fresh);
@@ -1360,6 +1508,7 @@ async function verifySchedulerWait(input, deps, ctx, action, budgets) {
             senderIds: input.senderIds,
             runState: ctx.runState,
             journal: false,
+            ...planScopeInput(input),
         });
         ctx.plan = fresh;
         const doneReason = normalizeDoneReason(doneReasonFromPlan(fresh));
@@ -1422,6 +1571,7 @@ async function gateVerify(input, deps, ctx, budgets) {
         senderIds: input.senderIds,
         runState: ctx.runState,
         journal: false,
+        ...planScopeInput(input),
     });
     ctx.plan = fresh;
     const doneReason = doneReasonFromPlan(fresh);
@@ -1474,19 +1624,19 @@ function classifyCaughtError(error, ctx) {
     };
 }
 async function heartbeatAndContinue(input, deps, ctx) {
-    const heartbeat = await deps.runClient.heartbeatRefillRun({
+    const yielded = await deps.runClient.yieldRefillRun({
         workspaceId: input.workspaceId,
         runId: ctx.runId,
         fence: ctx.fence,
     });
-    if (isLeaseLost(heartbeat))
+    if (isLeaseLost(yielded))
         return leaseLostResult(ctx);
     return {
         status: "in_progress",
         runId: ctx.runId,
         fence: ctx.fence,
         gate: ctx.gate,
-        guidance: "Per-invocation gate budget reached. Re-invoke refill_sends_v2 with this runId/fence to continue.",
+        guidance: "Per-invocation gate budget reached. Re-invoke public refill_sends with this durable run handle to continue.",
         journalPath: ctx.journalPath,
     };
 }
@@ -1500,6 +1650,7 @@ export async function runRefillV2Loop(input, deps) {
                 intent: input.intent,
                 senderIds: input.senderIds,
                 journal: true,
+                ...planScopeInput(input),
             });
             return { status: "dry_run", plan };
         }

package/dist/server.js

@@ -29,7 +29,6 @@ import { getEngageStateTool, setEngageStateTool, } from "./tools/engage-state.js
 import { bulkEnrichWithProspeo, enrichWithProspeo, getProspeoCredits, } from "./tools/enrichment.js";
 import { getRefillPlanV2 } from "./tools/evergreen-refill-plan.js";
 import { getCampaignFramework } from "./tools/framework.js";
-import { bootstrapFindLeads, cancelFindLeads, getFindLeadsRun, reissueFindLeadsWatchLink, updateFindLeadsRun, waitForFindLeadsRun, } from "./tools/find-leads-runs.js";
 import { confirmHarvestJobCompanies, searchHarvestJobs, } from "./tools/harvest-jobs.js";
 import { checkInboxReplyEligibility, getInboxThread, searchInboxThreads, sendInboxDraft, sendInboxManualReply, updateInboxDraft, } from "./tools/inbox.js";
 import { cancelLeadImport, confirmLeadList, confirmProspeoCompanyAccounts, getProviderPrompt, importLeads, listDncEntriesTool, loadCsvDncEntriesTool, loadCsvDomains, loadCsvLinkedinLeads, lookupSalesNavFilter, saveDomainFilters, searchApollo, searchProspeo, searchProspeoCompanies, searchSalesNav, searchSignals, selectPromisingPosts, setHeadlineICPCriteria, } from "./tools/leads.js";
@@ -37,7 +36,6 @@ import { fetchCompany, fetchCompanyPosts, fetchLinkedInPosts, fetchLinkedInProfi
 import { getCampaignNavigationState } from "./tools/navigation.js";
 import { addOnDemandLeads, createOnDemandCampaign, createOnDemandTable, initOnDemandSequence, pauseOnDemandCampaign, startOnDemandCampaign, } from "./tools/one-off.js";
 import { upsertRubric } from "./tools/processing.js";
-import { preflightFindLeadsProvider } from "./tools/provider-preflight.js";
 import { completeSenderResearch, getPostFindLeadsScoutRegistry, getSourceScoutRegistry, getSubskillAsset, getSubskillPrompt, listSubskillPrompts, searchSubskillPrompts, } from "./tools/prompts.js";
 import { waitForCampaignTableReady, waitForLeadListReady, } from "./tools/readiness.js";
 import { refreshSenderEngagementCommand } from "./tools/refresh-sender-engagement.js";
@@ -148,27 +146,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "wait_for_cli_login":
                 result = await handleWaitForCliLogin(args);
                 break;
-            case "bootstrap_find_leads":
-                result = await bootstrapFindLeads(args);
-                break;
-            case "get_find_leads_run":
-                result = await getFindLeadsRun(args);
-                break;
-            case "update_find_leads_run":
-                result = await updateFindLeadsRun(args);
-                break;
-            case "wait_for_find_leads_run":
-                result = await waitForFindLeadsRun(args);
-                break;
-            case "cancel_find_leads":
-                result = await cancelFindLeads(args);
-                break;
-            case "reissue_find_leads_watch_link":
-                result = await reissueFindLeadsWatchLink(args);
-                break;
-            case "preflight_find_leads_provider":
-                result = await preflightFindLeadsProvider(args);
-                break;
             case "bootstrap_engage":
                 result = await bootstrapEngage(args);
                 break;

package/dist/tools/auth.d.ts

@@ -11,6 +11,11 @@ export type AuthStatus = {
     tokenPresent: boolean;
     tokenPrefix: string | null;
     workspacesCount: number | null;
+    workspaceLock: {
+        enabled: boolean;
+        workspaceId: string | null;
+        required: boolean;
+    };
     checkedAt: string;
     /** Short message the LLM MUST show the user after auth succeeds. */
     _userNotice: string | null;

package/dist/tools/auth.js

@@ -1,6 +1,6 @@
 import * as fs from "fs";
 import { getApi, SellableApiError } from "../api.js";
-import { getConfig, getConfigPath, getResolvedConfigsDir } from "../auth.js";
+import { getConfig, getConfigPath, getEffectiveConfiguredWorkspaceId, getLockedWorkspaceId, getResolvedConfigsDir, isWorkspaceLockRequired, workspaceLockRequiredMessage, } from "../auth.js";
 import { checkForUpdates } from "../update-check.js";
 function maskToken(token) {
     if (token.length <= 10)
@@ -38,6 +38,8 @@ export async function getAuthStatus() {
     const checkedAt = new Date().toISOString();
     const update = await getUpdateStatus();
     let tokenPresent = false;
+    const workspaceLockRequired = isWorkspaceLockRequired();
+    const lockedWorkspaceId = getLockedWorkspaceId();
     const base = {
         ok: false,
         configPath,
@@ -50,27 +52,47 @@ export async function getAuthStatus() {
         tokenPresent: false,
         tokenPrefix: null,
         workspacesCount: null,
+        workspaceLock: {
+            enabled: Boolean(lockedWorkspaceId),
+            workspaceId: lockedWorkspaceId,
+            required: workspaceLockRequired,
+        },
         _userNotice: appendUpdateNotice(null, update),
         update,
         checkedAt,
     };
+    if (workspaceLockRequired && !lockedWorkspaceId) {
+        return {
+            ...base,
+            error: {
+                type: "workspace",
+                message: "Customer profile workspace lock is missing.",
+                guidance: workspaceLockRequiredMessage("get_auth_status"),
+            },
+        };
+    }
     try {
         const config = getConfig();
         tokenPresent = Boolean(config.token);
         base.activeEnvName = config.activeEnvName || null;
         const api = getApi();
         const { workspaces } = await api.get("/api/v3/workspaces");
-        const activeWorkspaceId = config.activeWorkspaceId || config.workspaceId || null;
+        const activeWorkspaceId = getEffectiveConfiguredWorkspaceId(config);
         const activeWorkspace = activeWorkspaceId
             ? workspaces.find((ws) => ws.id === activeWorkspaceId)
             : null;
+        const visibleWorkspacesCount = lockedWorkspaceId
+            ? activeWorkspace
+                ? 1
+                : 0
+            : workspaces.length;
         if (!activeWorkspaceId) {
             return {
                 ...base,
                 apiUrl: config.apiUrl || null,
                 tokenPresent,
                 tokenPrefix: maskToken(config.token),
-                workspacesCount: workspaces.length,
+                workspacesCount: visibleWorkspacesCount,
                 error: {
                     type: "workspace",
                     message: "No active workspace selected.",
@@ -87,22 +109,26 @@ export async function getAuthStatus() {
                 apiUrl: config.apiUrl || null,
                 tokenPresent,
                 tokenPrefix: maskToken(config.token),
-                workspacesCount: workspaces.length,
+                workspacesCount: visibleWorkspacesCount,
                 error: {
                     type: "workspace",
                     message: `Active workspace ${activeWorkspaceId} not found in access list.`,
-                    guidance: available
-                        ? `Available: ${available}. Run set_active_workspace with a valid ID.`
-                        : "Run list_workspaces to view available workspaces, then set_active_workspace.",
+                    guidance: lockedWorkspaceId
+                        ? "This profile is locked to a workspace that the configured Sellable token cannot access. Re-provision the customer profile from sellable-admin with the correct workspace token."
+                        : available
+                            ? `Available: ${available}. Run set_active_workspace with a valid ID.`
+                            : "Run list_workspaces to view available workspaces, then set_active_workspace.",
                 },
             };
         }
         const workspaceName = activeWorkspace.name || config.activeWorkspaceName || null;
         const envLabel = config.activeEnvName || null;
         const wsLabel = workspaceName || activeWorkspaceId;
-        const notice = envLabel
-            ? `You're in ${wsLabel} (${envLabel}).`
-            : `You're in ${wsLabel}.`;
+        const noticePrefix = lockedWorkspaceId
+            ? `You're locked to ${wsLabel}.`
+            : envLabel
+                ? `You're in ${wsLabel} (${envLabel}).`
+                : `You're in ${wsLabel}.`;
         return {
             ok: true,
             configPath,
@@ -114,8 +140,19 @@ export async function getAuthStatus() {
             activeWorkspaceName: workspaceName,
             tokenPresent,
             tokenPrefix: maskToken(config.token),
-            workspacesCount: workspaces.length,
-            _userNotice: appendUpdateNotice(notice, update),
+            workspacesCount: visibleWorkspacesCount,
+            workspaceLock: lockedWorkspaceId
+                ? {
+                    enabled: true,
+                    workspaceId: lockedWorkspaceId,
+                    required: workspaceLockRequired,
+                }
+                : {
+                    enabled: false,
+                    workspaceId: null,
+                    required: workspaceLockRequired,
+                },
+            _userNotice: appendUpdateNotice(noticePrefix, update),
             update,
             checkedAt,
             error: null,

package/dist/tools/campaign-message-preparation.d.ts

@@ -36,9 +36,16 @@ type StartPrepareMessagesInput = PrepareMessagesBaseInput & {
     requestSource?: string;
     senderId?: string;
     actionType?: string;
+    targetDate?: string;
+    refillLaneKey?: string;
+    sourceEpoch?: string;
 };
 type StatusPrepareMessagesInput = PrepareMessagesBaseInput;
 type CancelPrepareMessagesInput = PrepareMessagesBaseInput;
+type StopSatisfiedPrepareMessagesInput = PrepareMessagesBaseInput & {
+    jobId: string;
+    expectedUpdatedAt?: string;
+};
 export declare const campaignMessagePreparationToolDefinitions: ({
     name: string;
     description: string;
@@ -117,6 +124,18 @@ export declare const campaignMessagePreparationToolDefinitions: ({
                 enum: string[];
                 description: string;
             };
+            targetDate: {
+                type: string;
+                description: string;
+            };
+            refillLaneKey: {
+                type: string;
+                description: string;
+            };
+            sourceEpoch: {
+                type: string;
+                description: string;
+            };
             disableLowPassRateStop: {
                 type: string;
                 description: string;
@@ -126,6 +145,7 @@ export declare const campaignMessagePreparationToolDefinitions: ({
                 description: string;
             };
             jobId?: undefined;
+            expectedUpdatedAt?: undefined;
         };
         required: string[];
         additionalProperties: boolean;
@@ -160,13 +180,55 @@ export declare const campaignMessagePreparationToolDefinitions: ({
             autoContinue?: undefined;
             senderId?: undefined;
             actionType?: undefined;
+            targetDate?: undefined;
+            refillLaneKey?: undefined;
+            sourceEpoch?: undefined;
             disableLowPassRateStop?: undefined;
+            expectedUpdatedAt?: undefined;
         };
         additionalProperties: boolean;
         required?: undefined;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            jobId: {
+                type: string;
+            };
+            expectedUpdatedAt: {
+                type: string;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description?: undefined;
+            };
+            campaignId?: undefined;
+            tableId?: undefined;
+            targetPreparedMessages?: undefined;
+            maxRowsToCheck?: undefined;
+            batchSize?: undefined;
+            maxBatchRows?: undefined;
+            approvalMode?: undefined;
+            rowSelector?: undefined;
+            excludeRowIds?: undefined;
+            autoContinue?: undefined;
+            senderId?: undefined;
+            actionType?: undefined;
+            targetDate?: undefined;
+            refillLaneKey?: undefined;
+            sourceEpoch?: undefined;
+            disableLowPassRateStop?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 })[];
 export declare function startPrepareCampaignMessages(input: StartPrepareMessagesInput): Promise<unknown>;
 export declare function getPrepareCampaignMessagesStatus(input: StatusPrepareMessagesInput): Promise<unknown>;
 export declare function cancelPrepareCampaignMessages(input: CancelPrepareMessagesInput): Promise<unknown>;
+export declare function stopSatisfiedPrepareCampaignMessages(input: StopSatisfiedPrepareMessagesInput): Promise<unknown>;
 export {};

package/dist/tools/campaign-message-preparation.js

@@ -84,6 +84,18 @@ export const campaignMessagePreparationToolDefinitions = [
                     ],
                     description: "Optional refill-scope send action. InMail scopes treat open and paid InMail as one contact-reuse family.",
                 },
+                targetDate: {
+                    type: "string",
+                    description: "Exact sender-local YYYY-MM-DD refill target date.",
+                },
+                refillLaneKey: {
+                    type: "string",
+                    description: "Normalized refill lane identity from the canonical target plan.",
+                },
+                sourceEpoch: {
+                    type: "string",
+                    description: "Stable source/provider epoch; only a material epoch change resets zero-yield recurrence.",
+                },
                 disableLowPassRateStop: {
                     type: "boolean",
                     description: "Operator override for explicit fill/exhaust requests. When true, keep processing eligible rows even if the enriched sample pass rate is low. Still bounded by targetPreparedMessages and maxRowsToCheck.",
@@ -111,6 +123,23 @@ export const campaignMessagePreparationToolDefinitions = [
             additionalProperties: false,
         },
     },
+    {
+        name: "stop_satisfied_campaign_message_preparation",
+        description: "Cooperatively stop exactly one preparation job after the server rereads its persisted refill scope and proves its allocatable preparation deficit is zero. This never cancels table-wide workflow cells.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                jobId: { type: "string" },
+                expectedUpdatedAt: {
+                    type: "string",
+                    description: "Optional optimistic job updatedAt revision from status.",
+                },
+                workspaceId: { type: "string" },
+            },
+            required: ["jobId"],
+            additionalProperties: false,
+        },
+    },
     {
         name: "cancel_campaign_message_preparation",
         description: "Cancel an active campaign message preparation job and cancel the same pending workflow-table cells that the UI Cancel Pending Cells button would cancel. Launch remains a separate explicit start_campaign step.",
@@ -145,6 +174,9 @@ export function startPrepareCampaignMessages(input) {
         requestSource: input.requestSource,
         senderId: input.senderId,
         actionType: input.actionType,
+        targetDate: input.targetDate,
+        refillLaneKey: input.refillLaneKey,
+        sourceEpoch: input.sourceEpoch,
         ...(workspaceId ? { workspaceId } : {}),
     }, workspaceId ?? undefined);
 }
@@ -168,3 +200,12 @@ export function cancelPrepareCampaignMessages(input) {
         ...(workspaceId ? { workspaceId } : {}),
     }, workspaceId ?? undefined);
 }
+export function stopSatisfiedPrepareCampaignMessages(input) {
+    const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
+    return postPrepareMessages({
+        action: "stop_if_target_satisfied",
+        jobId: input.jobId,
+        expectedUpdatedAt: input.expectedUpdatedAt,
+        ...(workspaceId ? { workspaceId } : {}),
+    }, workspaceId ?? undefined);
+}