@sellable/mcp 0.1.541 → 0.1.543

package/dist/server.js

@@ -38,6 +38,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 { refreshSenderEngagementCommand } from "./tools/refresh-sender-engagement.js";
 import { refillSendsV2Command } from "./tools/refill-sends-v2.js";
 import { executeRefillSendsCommand } from "./tools/refill-sends.js";
 import { getRefillTargetPlan } from "./tools/refill-target-plan.js";
@@ -239,6 +240,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "run_scheduler_sweep":
                 result = await runSchedulerSweep(args);
                 break;
+            case "refresh_sender_engagement":
+                result = await refreshSenderEngagementCommand(args);
+                break;
             case "refill_sends":
                 result = await executeRefillSendsCommand(args);
                 break;

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);
+}

package/dist/tools/registry.d.ts

@@ -7419,6 +7419,45 @@ export declare const allTools: ({
         };
         required: string[];
     };
+} | {
+    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;
+    };
 } | {
     name: string;
     description: string;

package/dist/tools/registry.js

@@ -34,6 +34,7 @@ import { onDemandToolDefinitions } from "./one-off.js";
 import { processingToolDefinitions } from "./processing.js";
 import { promptToolDefinitions } from "./prompts.js";
 import { readinessToolDefinitions } from "./readiness.js";
+import { refreshSenderEngagementToolDefinitions } from "./refresh-sender-engagement.js";
 import { refillSendsV2ToolDefinitions } from "./refill-sends-v2.js";
 import { refillSendsToolDefinitions } from "./refill-sends.js";
 import { refillTargetPlanToolDefinitions } from "./refill-target-plan.js";
@@ -83,6 +84,7 @@ export const allTools = [
     ...processingToolDefinitions,
     ...rubricToolDefinitions,
     ...readinessToolDefinitions,
+    ...refreshSenderEngagementToolDefinitions,
     ...rowToolDefinitions,
     ...cellToolDefinitions,
     ...promptToolDefinitions,

package/package.json

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

package/skills/refill-sends-v2-workflow/core/flow.v1.json

@@ -239,6 +239,7 @@
         "record_engage_proven_search",
         "refill_sends",
         "refresh_paid_inmail_credits",
+        "refresh_sender_engagement",
         "revise_message_template_and_rerun",
         "save_domain_filters",
         "save_hook_research",

package/skills/refresh-sender-engagement/SKILL.md

@@ -19,10 +19,9 @@ allowed-tools:
   - mcp__sellable__get_campaign_table_schema
   - mcp__sellable__list_tables
   - mcp__sellable__get_rows_minimal
+  - mcp__sellable__refresh_sender_engagement
   - mcp__sellable__fetch_linkedin_posts
-  - mcp__sellable__select_promising_posts
   - mcp__sellable__fetch_post_engagers
-  - mcp__sellable__add_on_demand_leads
 ---
 
 # Refresh Sender Engagement
@@ -34,7 +33,7 @@ You are a pipeline supply agent. People who engage with a sender's LinkedIn post
 <inputs>
 The invoking prompt names the senders ("refresh sender engagement for csreyes92 and thomas"). Resolve each via `list_senders` (match name/handle/LinkedIn URL). With no names given, inspect the active workspace and refresh every connected sender that has an active/paused sender-owned Post Engagers campaign backed by Signal Discovery.
 
-Optional: lookback window (default: posts from the last 30 days), engagement sources (default `both` reactions+comments), target sender names/ids, maximum posts per sender (default 5, hard cap 5 unless the user explicitly asks for more), and target campaign ids/names when the user wants to force a specific campaign.
+Optional: target sender names/ids, `tableId` when the user wants to force a specific campaign table, maximum posts per sender (default 5, hard cap 5 unless the user explicitly asks for more), and maximum engager pages per tracked post.
 </inputs>
 
 <entrypoint>
@@ -53,39 +52,36 @@ suggest `refill-sends`.
 <objective>
 For each target sender/campaign:
 
-1. **Find active Signal Discovery/Post Engagers campaigns first**:
+1. **Authenticate and resolve workspace**:
    - Call `get_auth_status` and confirm the active workspace.
-   - Call `get_campaigns` and, when needed, `list_tables`/`get_campaign` to find candidate campaigns.
-   - Keep only active or paused campaign-backed sender-owned Post Engagers campaigns. Strong signals include campaign/table names like `<Sender> - Post Engagers`, `sourceProvider:"signal-discovery"`, sender attachment to exactly one sender, and source/list/table readback indicating post engagers.
-   - Exclude shared Signal Discovery lanes, Shared Cold Fallback lanes, archived/completed campaigns, non-campaign tables, direct/on-demand-only campaigns, and any campaign attached to multiple senders unless the user explicitly selected it and the readback proves it is sender-owned.
-   - If no matching campaign exists for a sender, report "no active Post Engagers Signal Discovery campaign — create one first" and skip; do not silently create campaigns.
-2. **Resolve the sender and source boundary**:
-   - Match each candidate campaign to its sender from `list_senders`/`get_sender`.
-   - Use the sender's own LinkedIn profile URL/handle as the only source author boundary.
-   - Never scrape third-party authors into a sender-owned Post Engagers campaign.
-3. **Find relevant sender-authored posts to refresh**:
-   - Call `fetch_linkedin_posts({ linkedinUrl: sender profile, limit: 25 })`.
-   - Keep original posts authored by that exact sender, not reposts, from the lookback window.
-   - Rank posts by recency, engagement count, and fit to the campaign's buyer/problem/topic. Prefer posts likely to attract the target buyer over generic company updates.
-   - If the campaign has an existing Signal Discovery/source state that names tracked/selected posts, prefer refreshing those posts when they are still inside the lookback window and relevant; otherwise choose the strongest recent sender-authored posts.
-   - When the product flow expects selected posts to be visible, call `select_promising_posts` before scraping.
-4. **Pull latest engagers**:
-   - For the top posts (up to 5 per sender per run), call `fetch_post_engagers({ postUrl, sources })`.
-   - Default `sources` to `"both"` unless the user requested reactions-only or comments-only.
-5. **Filter to ICP** using the campaign's existing headline ICP criteria (from `get_campaign` brief/rubrics/table schema). Judge each engager's headline against those criteria; exclude obvious non-fits, the sender's own colleagues, existing employees, students/job-seekers, competitors, and anyone with no usable headline. When the campaign has no criteria, keep likely decision-makers/operators and exclude weak-fit profiles.
-6. **Add net-new leads only**:
-   - Use `add_on_demand_leads({ tableId, leads, skipDuplicates: true })` with name, headline-derived title, profile URL, and source/post context where the tool accepts it.
-   - Dedupe is mandatory. Never disable dedupe on a scheduled run.
-   - Do not generate, approve, schedule, or send messages.
-7. **Report**: campaigns inspected, target campaigns selected, posts scanned, engagers found, ICP-passing, net-new added per sender/campaign. If a sender posted nothing in the window, say "no recent posts — nothing to refresh" (that is a truthful no-op, not a failure).
+   - If there is no active workspace or auth is missing, stop with the MCP guidance. Do not use local env files or repo scripts as a substitute for MCP auth.
+   - Resolve each target sender with `list_senders`/`get_sender`. Use the sender id returned by the product, not a guessed handle.
+2. **Use the typed product command first**:
+   - Call `refresh_sender_engagement` in `mode:"dry_run"` for each sender.
+   - Always pass `workspaceId`, `senderId`, and any user-specified `tableId`, `maxPosts`, or `maxEngagerPages`.
+   - Treat the dry-run response as the campaign/source boundary authority. It should identify the sender-owned Post Engagers slot, campaign, workflow table, source provider `campaign-tracked-post`, source table type `tracked_post_engager_source_list`, expected tracked posts, expected engager refresh/import work, and a `dryRunFingerprint`.
+   - If the typed command reports no eligible sender-owned Post Engagers campaign, no tracked posts, no recent posts, or a workspace/sender mismatch, report that exact blocker and stop for that sender. Do not silently create campaigns or fall back to shared lanes.
+3. **Gate writes with dry-run proof**:
+   - Never call `refresh_sender_engagement` in `mode:"apply"` before a successful dry run from this same run.
+   - For manual runs, show the target workspace, sender, campaign/table, source lead list, expected tracked posts, expected row/import impact, and `dryRunFingerprint`, then wait for explicit user approval before apply.
+   - For scheduled automations where the user has already authorized refreshes, apply is allowed only with the exact `dryRunFingerprint` from the immediately preceding dry run.
+   - If apply rejects the fingerprint as stale or mismatched, rerun dry-run and ask for approval again for manual runs.
+4. **Apply through the typed command only**:
+   - Call `refresh_sender_engagement({ mode:"apply", workspaceId, senderId, tableId?, maxPosts?, maxEngagerPages?, dryRunFingerprint })`.
+   - The apply path must materialize/refresh tracked posts, import deduped tracked-post engagers into the campaign table, and preserve product idempotency. Do not use `add_on_demand_leads` or raw table row writes for the same operation.
+5. **Read-only fallback is diagnostic only**:
+   - If the typed command is unavailable, use `get_subskill_prompt`/`search_subskill_prompts` and stop with `blocked: missing_refresh_sender_engagement_tool`.
+   - `fetch_linkedin_posts` and `fetch_post_engagers` may be used only to explain source availability or diagnose provider issues. They are not an alternate write path.
+6. **Report**: campaigns inspected, target campaign/table, tracked posts materialized/refreshed, engagers scanned, ICP-passing/importable, net-new rows imported, duplicates skipped, and any no-op reason per sender/campaign. If a sender posted nothing in the window, say "no recent posts — nothing to refresh" (that is a truthful no-op, not a failure).
 </objective>
 
 <safety>
-- LinkedIn operations here are read-only fetches plus adding rows to a campaign table. **No messages are generated, approved, or sent by this skill.**
+- LinkedIn operations here are read-only fetches plus a typed product import into a campaign table. **No messages are generated, approved, scheduled, or sent by this skill.**
 - Respect workspace boundaries: only add leads to campaigns in the active workspace, and only for senders that belong to it.
 - Respect campaign boundaries: only add engagers to the matched sender-owned Post Engagers campaign/table. Do not mix shared-lane engagers into sender-owned campaigns or sender-owned engagers into shared lanes.
 - Cap provider usage per run: at most 5 posts × `fetch_post_engagers` per sender. If the invoking automation wants more, it must say so explicitly.
-- Never call `start_campaign`, `attach_sequence`, `queue_campaign_cells`, `start_campaign_message_preparation`, approval tools, or any send/schedule tool.
+- Never call `start_campaign`, `attach_sequence`, `queue_campaign_cells`, `start_campaign_message_preparation`, approval tools, send/schedule tools, or shared-lane mutation tools.
+- Never create campaigns, change campaign status, change sender ownership, approve campaign cells, or start message prep as part of this refresh.
 </safety>
 
 <output>

package/skills/research/config.json

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