@sellable/mcp 0.1.557 → 0.1.558

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

@@ -1,11 +1,34 @@
+import { createHash } from "node:crypto";
+import { REFILL_CONTRACT_CACHE_VERSION, REFILL_CONTRACT_HASH, REFILL_CONTRACT_VERSION, renderRefillSafetyGuidance, } from "../refill-contract.js";
 import { appendIndexLine, appendJournalEvent, createRunJournal, renderBootstrapSection, renderCrashedAbandonedSection, renderExecutionEventSection, renderPlanSection, renderTerminalSection, } from "../refill-journal.js";
 import { writeRefillWorkspaceState } from "../refill-local-state.js";
-import { advanceRefillRunGateRemote, completeRefillRun, heartbeatRefillRun, recordRunOutcome, recordRunPlanned, refillRunStatus, startRefillRunRemote, } from "../refill-run-client.js";
+import { advanceRefillRunGateRemote, completeRefillRun, heartbeatRefillRun, recordRunOutcome, recordRunPlanned, refillRunStatus, startRefillRunRemote, yieldRefillRun, } from "../refill-run-client.js";
 import { runRefillV2Loop } from "../refill-run-loop.js";
-import { getPrepareCampaignMessagesStatus } from "./campaign-message-preparation.js";
+import { getPrepareCampaignMessagesStatus, stopSatisfiedPrepareCampaignMessages, } 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";
+function installedIdentityEnv(env, name, fallback) {
+    const value = env[name]?.trim();
+    return value || fallback;
+}
+export function resolveRefillV2InstalledIdentity(env = process.env) {
+    const mcpVersion = installedIdentityEnv(env, "SELLABLE_MCP_PACKAGE_VERSION", "unresolved-mcp");
+    return {
+        mcpVersion,
+        installVersion: installedIdentityEnv(env, "SELLABLE_INSTALL_PACKAGE_VERSION", "unresolved-install"),
+        pluginVersion: installedIdentityEnv(env, "SELLABLE_CODEX_PLUGIN_VERSION", "unresolved-plugin"),
+        cacheIdentity: installedIdentityEnv(env, "SELLABLE_PLUGIN_CACHE_IDENTITY", `mcp-package:${mcpVersion}`),
+    };
+}
+export const REFILL_V2_RUNTIME_IDENTITY = {
+    contract: {
+        version: REFILL_CONTRACT_VERSION,
+        hash: REFILL_CONTRACT_HASH,
+        cacheKey: REFILL_CONTRACT_CACHE_VERSION,
+    },
+    installed: resolveRefillV2InstalledIdentity(),
+};
 const FORBIDDEN_ACTIONS = [
     "Do not schedule sends.",
     "Do not send messages.",
@@ -18,7 +41,11 @@ 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.",
+        description: [
+            "Execute the server-internal refill loop behind public refill_sends; it is retained for dispatch compatibility but is not advertised.",
+            `contractHash=${REFILL_CONTRACT_HASH}`,
+            renderRefillSafetyGuidance(),
+        ].join(" "),
         inputSchema: {
             type: "object",
             properties: {
@@ -51,6 +78,18 @@ export const refillSendsV2ToolDefinitions = [
                     type: "string",
                     enum: ["auto", "evergreen", "plain", "active"],
                 },
+                targetDate: {
+                    type: "string",
+                    description: "Exact sender-local YYYY-MM-DD date.",
+                },
+                untilDate: {
+                    type: "string",
+                    description: "Inclusive sender-local YYYY-MM-DD through-date.",
+                },
+                horizonSendDays: {
+                    type: "number",
+                    description: "Positive sender-local send-day horizon.",
+                },
             },
             required: ["workspaceId"],
             additionalProperties: false,
@@ -68,6 +107,234 @@ function resumeHandle(input) {
         ? { runId: input.runId, fence: input.fence }
         : undefined;
 }
+function validDate(value, field) {
+    const trimmed = value.trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(trimmed) ||
+        new Date(`${trimmed}T00:00:00.000Z`).toISOString().slice(0, 10) !== trimmed) {
+        throw new Error(`${field} must be a valid YYYY-MM-DD date.`);
+    }
+    return trimmed;
+}
+function normalizeDateSelector(input) {
+    const selected = [
+        input.targetDate !== undefined,
+        input.untilDate !== undefined,
+        input.horizonSendDays !== undefined,
+    ].filter(Boolean).length;
+    if (selected > 1) {
+        throw new Error("Provide exactly one refill date selector.");
+    }
+    if (input.targetDate !== undefined) {
+        const targetDate = validDate(input.targetDate, "targetDate");
+        return {
+            dateSelector: { kind: "target_date", targetDate },
+            targetDate,
+        };
+    }
+    if (input.untilDate !== undefined) {
+        const untilDate = validDate(input.untilDate, "untilDate");
+        return {
+            dateSelector: { kind: "until_date", untilDate },
+            untilDate,
+        };
+    }
+    if (input.horizonSendDays !== undefined) {
+        if (!Number.isInteger(input.horizonSendDays) ||
+            input.horizonSendDays <= 0) {
+            throw new Error("horizonSendDays must be a positive integer.");
+        }
+        return {
+            dateSelector: {
+                kind: "horizon_send_days",
+                horizonSendDays: input.horizonSendDays,
+            },
+            horizonSendDays: input.horizonSendDays,
+        };
+    }
+    return { dateSelector: { kind: "scheduler_default" } };
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function text(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}
+function sortedUnique(values) {
+    return [
+        ...new Set(values.filter((value) => Boolean(value))),
+    ].sort((left, right) => left.localeCompare(right));
+}
+function sha256(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function targetPlanParts(targetPlan) {
+    const target = record(targetPlan.target) ?? {};
+    const plans = list(target.senderRefillPlans)
+        .map(record)
+        .filter((value) => value != null);
+    const actions = list(target.globalActionQueue)
+        .map(record)
+        .filter((value) => value != null);
+    return { target, plans, actions };
+}
+function stableIdsFromTargetPlan(targetPlan, input) {
+    const { plans, actions } = targetPlanParts(targetPlan);
+    const actionRecords = actions.map((action) => ({
+        action,
+        ids: record(action.ids) ?? {},
+        toolInput: record(action.toolInput) ?? {},
+    }));
+    const senderIds = sortedUnique([
+        ...(input.senderIds ?? []),
+        ...plans.map((plan) => text(plan.senderId)),
+        ...actionRecords.map(({ ids, toolInput }) => text(ids.senderId) ?? text(toolInput.senderId)),
+    ]);
+    const campaignIds = sortedUnique(actionRecords.map(({ ids, toolInput }) => text(ids.campaignId) ?? text(toolInput.campaignId)));
+    const tableIds = sortedUnique(actionRecords.map(({ ids, toolInput }) => text(ids.tableId) ?? text(toolInput.tableId)));
+    const actionIds = sortedUnique(actionRecords.map(({ action }) => text(action.actionKey) ?? text(action.type)));
+    const senderTimezones = Object.fromEntries(plans
+        .flatMap((plan) => list(plan.selectedDays))
+        .map(record)
+        .filter((day) => day != null)
+        .map((day) => [
+        text(day.senderId),
+        text(day.senderTimeZone) ?? text(day.timeZone),
+    ])
+        .filter((entry) => entry[0] != null && entry[1] != null)
+        .sort(([left], [right]) => left.localeCompare(right)));
+    return {
+        senderIds,
+        campaignIds,
+        tableIds,
+        actionIds,
+        senderTimezones,
+        actions: actionRecords,
+    };
+}
+function buildApprovalEnvelope(input) {
+    const workspaceId = normalizeWorkspaceId(input.workspaceId);
+    const date = normalizeDateSelector(input);
+    const stable = stableIdsFromTargetPlan(input.targetPlan, input);
+    const schedulerAction = stable.actions.find(({ action }) => action.type === "run_scheduler_sweep");
+    const schedulerInput = schedulerAction?.toolInput ?? {};
+    const expectedTargets = list(schedulerInput.expectedTargets);
+    const expectedTargetsHash = text(schedulerInput.expectedTargetsHash) ?? sha256(expectedTargets);
+    const maxPlacements = typeof schedulerInput.maxPlacements === "number" &&
+        Number.isInteger(schedulerInput.maxPlacements) &&
+        schedulerInput.maxPlacements > 0
+        ? schedulerInput.maxPlacements
+        : 150;
+    const scope = {
+        version: 2,
+        workspaceId,
+        intent: input.intent ?? "auto",
+        senderIds: stable.senderIds,
+        campaignIds: stable.campaignIds,
+        tableIds: stable.tableIds,
+        actionIds: stable.actionIds,
+        approvalMode: input.approvalMode ?? "approve",
+        dateSelector: date.dateSelector,
+        senderTimezones: stable.senderTimezones,
+        expectedTargetsHash,
+        maxPlacements,
+        contract: { ...REFILL_V2_RUNTIME_IDENTITY.contract },
+        installed: { ...REFILL_V2_RUNTIME_IDENTITY.installed },
+    };
+    const scopeHash = sha256(scope);
+    const targetShapeRevision = text(input.targetPlan.targetShapeRevision) ??
+        text(record(input.targetPlan.target)?.targetShapeRevision) ??
+        "missing_target_shape_revision";
+    const actionFingerprint = text(stable.actions[0]?.action.actionKey) ??
+        text(stable.actions[0]?.action.type) ??
+        "no_action";
+    const sideEffectEnvelope = sortedUnique(stable.actions.map(({ action }) => text(action.type)));
+    const approvalExpiresAt = input.approvalExpiresAt ??
+        new Date((input.now ?? new Date()).getTime() + 15 * 60_000).toISOString();
+    const fingerprintFields = {
+        scopeHash,
+        targetShapeRevision,
+        actionFingerprint,
+        expectedTargetsHash,
+        sideEffectEnvelope,
+        maxPlacements,
+        approvalExpiresAt,
+    };
+    const approval = {
+        status: "awaiting_approval",
+        ...fingerprintFields,
+        approvalFingerprint: sha256(fingerprintFields),
+    };
+    return { scope, scopeHash, approval, date };
+}
+export async function prepareRefillSendsV2Approval(input) {
+    const envelope = buildApprovalEnvelope(input);
+    const started = await startRefillRunRemote({
+        workspaceId: envelope.scope.workspaceId,
+        config: {
+            scope: envelope.scope,
+            scopeHash: envelope.scopeHash,
+            approval: envelope.approval,
+        },
+        runState: {
+            version: 1,
+            scope: envelope.scope,
+            scopeHash: envelope.scopeHash,
+            approval: envelope.approval,
+            senderCursors: [],
+            laneCooldowns: [],
+            passRates: [],
+        },
+    });
+    const result = record(started) ?? {};
+    const runId = text(result.runId);
+    const fence = typeof result.fence === "number" && Number.isFinite(result.fence)
+        ? result.fence
+        : null;
+    if (!runId || fence == null) {
+        return {
+            status: "blocked",
+            blocker: text(result.blocker) ?? "approval_run_unavailable",
+            response: started,
+        };
+    }
+    const persistedConfig = record(result.config);
+    const persistedScope = record(persistedConfig?.scope) ?? envelope.scope;
+    const persistedApproval = record(persistedConfig?.approval) ??
+        envelope.approval;
+    return {
+        ...persistedApproval,
+        status: "awaiting_approval",
+        runId,
+        fence,
+        scope: persistedScope,
+    };
+}
+function validateApprovalEcho(envelope, echo, now = new Date()) {
+    const fields = [
+        "scopeHash",
+        "targetShapeRevision",
+        "actionFingerprint",
+        "expectedTargetsHash",
+        "approvalExpiresAt",
+        "approvalFingerprint",
+    ];
+    const changed = fields.filter((field) => echo[field] !== envelope.approval[field]);
+    if (Date.parse(envelope.approval.approvalExpiresAt) <= now.getTime()) {
+        return { ok: false, blocker: "approval_expired", changed };
+    }
+    return changed.length === 0
+        ? { ok: true }
+        : {
+            ok: false,
+            blocker: "approval_fingerprint_mismatch",
+            changed,
+        };
+}
 async function maybeAddLostFenceGuidance(result, input) {
     if (result.status !== "blocked" ||
         result.blocker !== "lease_lost" ||
@@ -94,12 +361,45 @@ async function maybeAddLostFenceGuidance(result, input) {
 }
 export async function refillSendsV2Command(input) {
     const workspaceId = normalizeWorkspaceId(input.workspaceId);
+    const date = normalizeDateSelector(input);
+    let resolvedScope = input.scope;
+    let resolvedScopeHash = input.scopeHash;
+    let resolvedApproval = input.approval;
+    if (input.targetPlan && input.approvalEcho) {
+        const envelope = buildApprovalEnvelope({
+            workspaceId,
+            intent: input.intent,
+            senderIds: input.senderIds,
+            approvalMode: input.approvalMode,
+            targetDate: input.targetDate,
+            untilDate: input.untilDate,
+            horizonSendDays: input.horizonSendDays,
+            targetPlan: input.targetPlan,
+            approvalExpiresAt: input.approvalEcho.approvalExpiresAt,
+        });
+        const validation = validateApprovalEcho(envelope, input.approvalEcho);
+        if (!validation.ok) {
+            return {
+                status: "blocked",
+                blocker: validation.blocker,
+                guidance: "The durable refill approval no longer matches fresh scope; render and approve a new packet before mutation.",
+                report: { changed: validation.changed, fresh: envelope.approval },
+                readOnly: false,
+                forbiddenActions: FORBIDDEN_ACTIONS,
+                boundedAuthority: BOUNDED_AUTHORITY,
+            };
+        }
+        resolvedScope = envelope.scope;
+        resolvedScopeHash = envelope.scopeHash;
+        resolvedApproval = envelope.approval;
+    }
     if (input.dryRun) {
         const plan = await getRefillPlanV2({
             workspaceId,
             intent: input.intent,
             senderIds: input.senderIds,
             journal: true,
+            ...date,
         });
         return {
             ...plan,
@@ -115,11 +415,16 @@ export async function refillSendsV2Command(input) {
         senderIds: input.senderIds,
         approvalMode: input.approvalMode ?? "approve",
         resume: resumeHandle(input),
+        ...date,
+        scope: resolvedScope,
+        scopeHash: resolvedScopeHash,
+        approval: resolvedApproval,
     }, {
         runClient: {
             startRefillRunRemote,
             refillRunStatus,
             heartbeatRefillRun,
+            yieldRefillRun,
             advanceRefillRunGateRemote,
             recordRunPlanned,
             recordRunOutcome,
@@ -131,12 +436,16 @@ export async function refillSendsV2Command(input) {
             senderIds: planInput.senderIds,
             runState: planInput.runState,
             journal: planInput.journal,
+            targetDate: planInput.targetDate,
+            untilDate: planInput.untilDate,
+            horizonSendDays: planInput.horizonSendDays,
         }),
         executors: {
             executeOneYoloPrimitive,
             executeStartCampaignPrimitive,
             refreshPaidInmailCreditsWithRetry,
             getPrepareCampaignMessagesStatus,
+            stopSatisfiedPrepareCampaignMessages,
             refillPrepareRequestHash,
             prepareRowSelectorValue,
         },