@sellable/mcp 0.1.408 → 0.1.410

package/README.md

@@ -16,7 +16,7 @@ Each message gets 5+ minutes of Claude attention with deep research - no other t
 
 ### Prompt Source Of Truth
 
-There are six public Sellable entrypoints shared across hosts:
+There are seven public Sellable entrypoints shared across hosts:
 
 - `sellable:create-campaign`
 - `sellable:create-ab-test`
@@ -24,6 +24,7 @@ There are six public Sellable entrypoints shared across hosts:
 - `sellable:foundation`
 - `sellable:content`
 - `sellable:create-post`
+- `sellable:refill-sends`
 
 The create-campaign public wrapper at
 `mcp/sellable/skills/create-campaign/SKILL.md` handles auth/bootstrap and loads
@@ -63,6 +64,13 @@ reader value, validates proof/AI tells, and saves content artifacts under
 
 - `mcp/sellable/skills/create-post/SKILL.md`
 
+The refill-sends public command wrapper plans and executes approval-gated send
+refills. It supports `--yolo` and optional sender selectors such as
+`--sender "Christian Reyes"` or typed MCP calls to `refill_sends({ yolo,
+senders })` from:
+
+- `mcp/sellable/skills/refill-sends/SKILL.md`
+
 Keep `create-campaign-v2` and `load-voice` internal. Do not advertise either as
 a public command. `load-voice` remains a direct MCP utility for generic writing
 surfaces that are not posts or campaigns.
@@ -186,10 +194,10 @@ The installer does the full local setup:
 After the installer passes, fully quit and reopen Codex Desktop. Start a new
 thread and select `Sellable Create Campaign`, `Sellable Create A/B Test`,
 `Sellable Create Evergreen Campaigns`, `Sellable Foundation`,
-`Sellable Content`, or `Sellable Create Post`; or invoke
+`Sellable Content`, `Sellable Create Post`, or `Sellable Refill Sends`; or invoke
 `$sellable:create-campaign`, `$sellable:create-ab-test`,
 `$sellable:create-evergreen-campaigns`, `$sellable:foundation`,
-`$sellable:content`, or `$sellable:create-post`. If the app still says
+`$sellable:content`, `$sellable:create-post`, or `$sellable:refill-sends`. If the app still says
 `mcp__sellable__*` tools are missing after the installer passes, check that
 `~/.codex/config.toml` contains both `[marketplaces.sellable]` and
 `[plugins."sellable@sellable"]`.
@@ -206,12 +214,14 @@ Use these names consistently:
 - Claude Code command: `/sellable:foundation`
 - Claude Code command: `/sellable:content`
 - Claude Code command: `/sellable:create-post`
+- Claude Code command: `/sellable:refill-sends`
 - Codex command: `$sellable:create-campaign`
 - Codex command: `$sellable:create-ab-test`
 - Codex command: `$sellable:create-evergreen-campaigns`
 - Codex command: `$sellable:foundation`
 - Codex command: `$sellable:content`
 - Codex command: `$sellable:create-post`
+- Codex command: `$sellable:refill-sends`
 - Codex Desktop plugin: `sellable@sellable`
 - Codex visible skill: `Sellable Create Campaign`
 - Codex visible skill: `Sellable Create A/B Test`
@@ -219,14 +229,17 @@ Use these names consistently:
 - Codex visible skill: `Sellable Foundation`
 - Codex visible skill: `Sellable Content`
 - Codex visible skill: `Sellable Create Post`
+- Codex visible skill: `Sellable Refill Sends`
 - Codex skill frontmatter name: `create-campaign`
 - Codex skill frontmatter name: `create-ab-test`
 - Codex skill frontmatter name: `create-evergreen-campaigns`
 - Codex skill frontmatter name: `foundation`
 - Codex skill frontmatter name: `content`
 - Codex skill frontmatter name: `create-post`
+- Codex skill frontmatter name: `refill-sends`
 - MCP server name: `sellable`
 - Internal workflow prompt: `create-campaign-v2`
+- Internal workflow prompt: `refill-sends-workflow`
 - Internal/backward-compatible memory prompt: `interview`
 
 Never tell users to run `/sellable:create-campaign-v2`,
@@ -279,6 +292,13 @@ Use the create-campaign skill:
 /sellable:create-campaign
 ```
 
+Use the refill command for sender send refills:
+
+```
+/sellable:refill-sends --yolo
+/sellable:refill-sends --sender "Christian Reyes" --sender "Thomas Nobbs"
+```
+
 Then describe intent naturally, for example:
 
 - "Let's make a campaign with sellable"
@@ -299,6 +319,13 @@ Use the Codex skill entrypoint:
 $sellable:create-campaign
 ```
 
+Use the Codex refill command with the same flags:
+
+```
+$sellable:refill-sends --yolo
+$sellable:refill-sends --sender "Christian Reyes" --sender "Thomas Nobbs"
+```
+
 Installed skill package path:
 
 - `~/.codex/plugins/cache/sellable/sellable/<version>/skills/sellable-create-campaign/SKILL.md`

package/dist/server.js

@@ -37,6 +37,7 @@ import { addOnDemandLeads, createOnDemandCampaign, createOnDemandTable, initOnDe
 import { upsertRubric } from "./tools/processing.js";
 import { completeSenderResearch, getPostFindLeadsScoutRegistry, getSourceScoutRegistry, getSubskillAsset, getSubskillPrompt, listSubskillPrompts, searchSubskillPrompts, } from "./tools/prompts.js";
 import { waitForCampaignTableReady, waitForLeadListReady, } from "./tools/readiness.js";
+import { refillSendsCommand } from "./tools/refill-sends.js";
 import { allTools } from "./tools/registry.js";
 import { getRows, getTableRows, getTableRowsMinimal } from "./tools/rows.js";
 import { addRubricItem, checkRubric, deleteRubricItem, draftRubrics, saveRubrics, selectNecessaryRubrics, updateRubricItem, waitForRubricResults, } from "./tools/rubrics.js";
@@ -217,6 +218,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_campaign_refill_state":
                 result = await getCampaignRefillState(args);
                 break;
+            case "refill_sends":
+                result = refillSendsCommand(args);
+                break;
             case "setup_evergreen_campaigns":
                 result = await setupEvergreenCampaigns(args);
                 markEvergreenSetupCampaignsDirty(args);

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

@@ -0,0 +1,113 @@
+type RefillSendsIntent = "plain" | "active" | "evergreen";
+type RefillSendsApprovalMode = "approve" | "mark_ready";
+type RefillSendsCommandInput = {
+    yolo?: boolean;
+    senders?: string[];
+    senderIds?: string[];
+    senderNames?: string[];
+    horizonSendDays?: number;
+    campaignId?: string;
+    tableId?: string;
+    intent?: RefillSendsIntent;
+    approvalMode?: RefillSendsApprovalMode;
+};
+export declare const refillSendsToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            yolo: {
+                type: string;
+                description: string;
+            };
+            senders: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            senderIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            senderNames: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            horizonSendDays: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+            intent: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            approvalMode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: never[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function refillSendsCommand(input?: RefillSendsCommandInput): {
+    command: string;
+    tool: string;
+    promptName: string;
+    workflowPromptName: string;
+    yolo: boolean;
+    intent: RefillSendsIntent;
+    horizonSendDays: number;
+    approvalMode: RefillSendsApprovalMode;
+    campaignId: string | null;
+    tableId: string | null;
+    senderScope: string;
+    senderSelectors: {
+        senders: string[];
+        senderIds: string[];
+        senderNames: string[];
+    };
+    firstOperationalSteps: string[];
+    approvalContract: string;
+    forbiddenActions: string[];
+    hostExamples: {
+        claude: string[];
+        codex: string[];
+        mcpTool: {
+            name: string;
+            arguments: {
+                yolo: boolean;
+                senders: string[];
+                senderIds: string[];
+                senderNames: string[];
+                horizonSendDays: number;
+                campaignId: string | undefined;
+                tableId: string | undefined;
+                intent: RefillSendsIntent;
+                approvalMode: RefillSendsApprovalMode;
+            };
+        };
+    };
+};
+export {};

package/dist/tools/refill-sends.js

@@ -0,0 +1,150 @@
+const DEFAULT_HORIZON_SEND_DAYS = 2;
+function normalizeStrings(values) {
+    if (!Array.isArray(values))
+        return [];
+    return [
+        ...new Set(values
+            .map((value) => (typeof value === "string" ? value.trim() : ""))
+            .filter(Boolean)),
+    ];
+}
+function normalizeHorizonSendDays(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_HORIZON_SEND_DAYS;
+    }
+    return Math.max(1, Math.min(7, Math.floor(value)));
+}
+export const refillSendsToolDefinitions = [
+    {
+        name: "refill_sends",
+        description: "Typed command entrypoint for Sellable refill sends. Accepts --yolo semantics and optional sender selectors, then returns the bounded execution contract for the skill-led refill workflow. This tool does not mutate campaigns, import leads, approve messages, schedule sends, launch, archive, delete, or write scheduler rows.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                yolo: {
+                    type: "boolean",
+                    description: "When true, auto-accept the rendered bounded refill packet after the required fresh state reread. Without sender selectors, yolo means all eligible healthy senders enrolled in active campaign-backed sequence campaigns.",
+                },
+                senders: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional sender selectors as names or ids. Use this for command text like --sender 'Christian Reyes'. Exact resolution still happens through list_senders before mutation.",
+                },
+                senderIds: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional exact Sender.id values to scope refill work.",
+                },
+                senderNames: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional sender display names to resolve through list_senders before campaign selection.",
+                },
+                horizonSendDays: {
+                    type: "number",
+                    minimum: 1,
+                    maximum: 7,
+                    description: "Number of sender-local send days to fill. Defaults to 2.",
+                },
+                campaignId: {
+                    type: "string",
+                    description: "Optional exact CampaignOffer.id to narrow routing. Do not pass campaign names.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional exact WorkflowTable.id to narrow routing. Do not pass table names.",
+                },
+                intent: {
+                    type: "string",
+                    enum: ["plain", "active", "evergreen"],
+                    description: 'Route intent. Use "plain" for normal refill/load requests unless the user explicitly says active or evergreen.',
+                },
+                approvalMode: {
+                    type: "string",
+                    enum: ["approve", "mark_ready"],
+                    description: 'Preparation mode for the final packet. Use "approve" only when the user asked to fill/schedule sender sends; otherwise default to "mark_ready".',
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+];
+export function refillSendsCommand(input = {}) {
+    const senders = normalizeStrings(input.senders);
+    const senderIds = normalizeStrings(input.senderIds);
+    const senderNames = normalizeStrings(input.senderNames);
+    const hasSenderSelectors = senders.length > 0 || senderIds.length > 0 || senderNames.length > 0;
+    const yolo = input.yolo === true;
+    const horizonSendDays = normalizeHorizonSendDays(input.horizonSendDays);
+    const intent = input.intent ?? "plain";
+    const approvalMode = input.approvalMode ?? (yolo ? "approve" : "mark_ready");
+    const senderScope = hasSenderSelectors
+        ? "selected_senders"
+        : yolo
+            ? "all_eligible_healthy_senders_enrolled_in_active_campaign_backed_sequences"
+            : "ask_user_for_eligible_enrolled_senders_before_mutation";
+    return {
+        command: "refill-sends",
+        tool: "refill_sends",
+        promptName: "refill-sends",
+        workflowPromptName: "refill-sends-workflow",
+        yolo,
+        intent,
+        horizonSendDays,
+        approvalMode,
+        campaignId: input.campaignId ?? null,
+        tableId: input.tableId ?? null,
+        senderScope,
+        senderSelectors: {
+            senders,
+            senderIds,
+            senderNames,
+        },
+        firstOperationalSteps: [
+            'Load get_subskill_prompt({ subskillName: "refill-sends-workflow" }) before any product operation.',
+            `Resolve route with resolve_campaign_fill_route({ intent: "${intent}"${input.campaignId ? `, campaignId: "${input.campaignId}"` : ""}${input.tableId ? `, tableId: "${input.tableId}"` : ""} }).`,
+            "Call list_senders and get_sender_routing, then resolve sender selectors against active enrolled campaign-backed sequence senders.",
+            "Read get_campaign_refill_state for enough exact candidate campaigns to pick the best per-sender target by recent/future scheduler-owned sends, then recent result evidence, then source health.",
+            "Fresh reread get_campaign_refill_state immediately before any import, prep, approval, or horizon-fill mutation.",
+        ],
+        approvalContract: yolo
+            ? "Auto-accept only the rendered bounded refill packet after fresh reread. Stop if sender set, route, ids, caps, dates, blockers, or side-effect class drift."
+            : hasSenderSelectors
+                ? "Ask the final Accept/Decline structured approval question before mutation, including workspace, sender scope, campaign table, exact ids, caps/dates, side effects, forbidden actions, and stop condition."
+                : "Ask which eligible enrolled senders to refill first, then ask the final Accept/Decline structured approval question before mutation.",
+        forbiddenActions: [
+            "start_campaign",
+            "launch or send",
+            "archive or delete cleanup",
+            "direct scheduler writes",
+            "sender reassignment",
+            "campaigns outside the rendered eligible sender packet",
+            "on-demand or unrelated active-campaign fallback unless the refill workflow proves the selected same-sender lane is blocked or exhausted",
+        ],
+        hostExamples: {
+            claude: [
+                "/sellable:refill-sends --yolo",
+                '/sellable:refill-sends --sender "Christian Reyes" --sender "Thomas Nobbs"',
+            ],
+            codex: [
+                "$sellable:refill-sends --yolo",
+                '$sellable:refill-sends --sender "Christian Reyes" --sender "Thomas Nobbs"',
+            ],
+            mcpTool: {
+                name: "refill_sends",
+                arguments: {
+                    yolo,
+                    senders,
+                    senderIds,
+                    senderNames,
+                    horizonSendDays,
+                    campaignId: input.campaignId,
+                    tableId: input.tableId,
+                    intent,
+                    approvalMode,
+                },
+            },
+        },
+    };
+}

package/dist/tools/registry.js

@@ -33,6 +33,7 @@ import { onDemandToolDefinitions } from "./one-off.js";
 import { processingToolDefinitions } from "./processing.js";
 import { promptToolDefinitions } from "./prompts.js";
 import { readinessToolDefinitions } from "./readiness.js";
+import { refillSendsToolDefinitions } from "./refill-sends.js";
 import { rowToolDefinitions } from "./rows.js";
 import { rubricToolDefinitions } from "./rubrics.js";
 import { senderRoutingToolDefinitions } from "./sender-routing.js";
@@ -49,6 +50,7 @@ export const allTools = [
     ...campaignAbTestToolDefinitions,
     ...campaignFillRoutingToolDefinitions,
     ...campaignRefillStateToolDefinitions,
+    ...refillSendsToolDefinitions,
     ...setupEvergreenCampaignsToolDefinitions,
     ...campaignHorizonFillToolDefinitions,
     ...campaignMessagePreparationToolDefinitions,

package/package.json

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

package/skills/refill-sends/SKILL.md

@@ -3,6 +3,13 @@ name: refill-sends
 description: Plan regular campaign and evergreen campaign send refill work through the skill-led refill workflow.
 visibility: public
 allowed-tools:
+  - mcp__sellable__refill_sends
+  - mcp__sellable__get_auth_status
+  - mcp__sellable__start_cli_login
+  - mcp__sellable__wait_for_cli_login
+  - mcp__sellable__get_active_workspace
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__set_active_workspace
   - mcp__sellable__get_subskill_prompt
   - mcp__sellable__search_subskill_prompts
   - mcp__sellable__list_senders
@@ -45,8 +52,38 @@ allowed-tools:
 
 # Refill Sends
 
-Use this public wrapper for plain operator requests such as "fill", "refill sends",
-"max out sends", "load everyone up", or "fill horizon sends".
+Use this public command wrapper for plain operator requests such as "fill",
+"refill sends", "max out sends", "load everyone up", or "fill horizon sends".
+
+Host command names:
+
+- Claude Code: `/sellable:refill-sends`
+- Codex: `$sellable:refill-sends`
+
+Accepted invocation flags in the same user request:
+
+- `--yolo`: auto-accept the rendered bounded refill packet after the required
+  fresh state reread.
+- `--sender <name-or-id>`: scope to a specific sender; repeat for multiple
+  senders.
+- `senderIds: <id>, <id>` or `senderNames: <name>, <name>`: explicit selector
+  alternatives when the host preserves natural-language arguments better than
+  shell-style flags.
+
+When the host can call typed MCP tools, start with:
+
+```text
+refill_sends({ yolo?: boolean, senders?: string[], senderIds?: string[], senderNames?: string[], horizonSendDays?: number })
+```
+
+That command helper only normalizes arguments and returns the execution
+contract. It does not mutate. Continue with the workflow below for route
+selection, state rereads, approval gating, source import, preparation, and
+bounded approval.
+
+First call `get_auth_status({})`. If auth or active workspace is not OK, follow
+the returned login/workspace guidance before route resolution. Do not run refill
+research against an implicit or guessed workspace.
 
 Treat "refill senders", "fill senders", "load everyone up", and "max out
 senders" as sender-scoped requests. The target set is senders enrolled in active