@sellable/mcp 0.1.113 → 0.1.115

package/agents/source-scout-linkedin-engagement.md

@@ -17,14 +17,22 @@ Use the inherited Sellable MCP tools when available:
 - `search_signals` to find recent post lanes. Include `campaignOfferId` whenever
   the parent provides one so selected searches/lists stay attached to the
   campaign.
-- `fetch_post_engagers` to sample engagers from selected posts.
+- `select_promising_posts` to promote the exact posts you will sample into the
+  campaign UI before fetching engagers. In campaign-attached runs, do this
+  before the first `fetch_post_engagers` call so the user can see which posts
+  are being sampled.
+- `fetch_post_engagers` to sample engagers from promoted/selected posts.
 
 Process:
 
 1. Read the campaign brief, kickoff doc, or lane prompt supplied by the parent.
 2. Search 3-5 keyword/topic lanes, favoring fresh posts from the last 7-14 days.
-3. Select 3-5 promising posts when available.
-4. Fetch or sample engagers for selected posts and score rough ICP fit from visible headline/display-name cues only. Do not enrich people during viability estimation.
+3. Select 3-5 promising posts when available. If a `campaignOfferId` was
+   supplied, call `select_promising_posts({ campaignOfferId, selectionMode:
+"replace", selections, headlineICPCriteria, currentStep:
+"signal-discovery" })` before sampling so the watched Signal Discovery table
+   shows the promoted posts.
+4. Fetch or sample engagers for promoted posts and score rough ICP fit from visible headline/display-name cues only. Do not enrich people during viability estimation.
 5. Estimate usable prospects per selected post from sampled pass rate. If the sample is good but volume is low, say how many more similar posts should be added or scraped.
 6. Return false positives and dead ends explicitly.
 

package/dist/tools/campaigns.js

@@ -25,6 +25,9 @@ export function buildWatchUrl(config, path) {
     if (workspaceId && !url.searchParams.has("workspaceId")) {
         url.searchParams.set("workspaceId", workspaceId);
     }
+    if (config.token && !url.searchParams.has("token")) {
+        url.searchParams.set("token", config.token);
+    }
     return url.toString();
 }
 export function getCampaignBuilderWatchModeParam() {

package/dist/tools/context.d.ts

@@ -81,7 +81,8 @@ export declare function getCampaignContext(input: GetCampaignContextInput): Prom
         };
         watchUrl: {
             urlPresent: boolean;
-            direct: boolean | undefined;
+            direct: boolean;
+            autoLogin: boolean;
             redirectPath: string | null;
         };
         table: {

package/dist/tools/context.js

@@ -179,6 +179,7 @@ export function markCampaignContextDirty(campaignId, reason) {
             watchUrl: {
                 urlPresent: false,
                 direct: false,
+                autoLogin: false,
                 redirectPath: null,
             },
             table: {

package/dist/tools/leads.js

@@ -1047,7 +1047,7 @@ export const leadToolDefinitions = [
     },
     {
         name: "select_promising_posts",
-        description: "Select the most promising LinkedIn posts for lead scraping AND provide headline ICP criteria. Use the selectionTarget returned by search_signals (default 3).",
+        description: "Select the most promising LinkedIn posts for lead scraping AND provide headline ICP criteria. Use the selectionTarget returned by search_signals (default 3). In campaign-attached sampling, call select_promising_posts first to promote the sampled posts into the watched UI before fetch_post_engagers.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/linkedin.js

@@ -21,7 +21,7 @@ export const linkedinToolDefinitions = [
     },
     {
         name: "fetch_post_engagers",
-        description: "Fetch people who engaged with a LinkedIn post (reactions and/or comments). Returns deduplicated engagers with name, headline, profileUrl, and source. Use 'comments' for lead magnets to get people who actively engaged. Uses smart rate limiting and parallel fetching.",
+        description: "Fetch people who engaged with a LinkedIn post (reactions and/or comments). Returns deduplicated engagers with name, headline, profileUrl, and source. Use 'comments' for lead magnets to get people who actively engaged. Uses smart rate limiting and parallel fetching. In campaign-attached Signal Discovery sampling, call select_promising_posts first to promote the sampled posts into the watched UI.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/navigation.d.ts

@@ -81,7 +81,8 @@ export declare function computeCampaignNavigationStateFromCampaign(campaign: Cam
     };
     watchUrl: {
         urlPresent: boolean;
-        direct: boolean | undefined;
+        direct: boolean;
+        autoLogin: boolean;
         redirectPath: string | null;
     };
     table: {
@@ -125,7 +126,8 @@ export declare function getCampaignNavigationState(input: GetCampaignNavigationS
     };
     watchUrl: {
         urlPresent: boolean;
-        direct: boolean | undefined;
+        direct: boolean;
+        autoLogin: boolean;
         redirectPath: string | null;
     };
     table: {

package/dist/tools/navigation.js

@@ -385,7 +385,9 @@ function parseWatchUrl(watchUrl, campaignId) {
     if (!watchUrl) {
         return {
             urlPresent: false,
+            direct: false,
             signed: false,
+            autoLogin: false,
             redirectPath: null,
             warning: null,
         };
@@ -398,11 +400,15 @@ function parseWatchUrl(watchUrl, campaignId) {
                 url.searchParams.get("mode") === "codex" ||
                 url.searchParams.get("mode") === "watch");
         if (isDirectCampaignUrl) {
+            const autoLogin = Boolean(url.searchParams.get("token"));
             return {
                 urlPresent: true,
                 direct: true,
+                autoLogin,
                 redirectPath: `${url.pathname}?${url.searchParams.toString()}`.replace(/\?$/, ""),
-                warning: null,
+                warning: autoLogin
+                    ? null
+                    : "Watch URL is direct but missing token auto-login. Recover a fresh /campaign-builder/{campaignId}?mode={claude|codex}&token=... watch link before asking the user to open it.",
             };
         }
         const redirect = url.searchParams.get("redirect");
@@ -413,18 +419,20 @@ function parseWatchUrl(watchUrl, campaignId) {
         return {
             urlPresent: true,
             direct: false,
+            autoLogin: false,
             redirectPath: decodedRedirect,
             warning: isLegacySigned
-                ? "Watch URL still uses a tokenized /auth/continue handoff. Return the safe direct /campaign-builder/{campaignId}?mode={claude|codex} watch URL instead."
-                : "Watch URL is not a safe direct /campaign-builder/{campaignId}?mode={claude|codex} watch link.",
+                ? "Watch URL still uses a tokenized /auth/continue handoff. Return the direct /campaign-builder/{campaignId}?mode={claude|codex}&token=... watch URL instead."
+                : "Watch URL is not a direct /campaign-builder/{campaignId}?mode={claude|codex}&token=... watch link.",
         };
     }
     catch {
         return {
             urlPresent: true,
             direct: false,
+            autoLogin: false,
             redirectPath: null,
-            warning: "Watch URL is malformed; recover a fresh safe direct campaign-builder watch link before browser handoff.",
+            warning: "Watch URL is malformed; recover a fresh direct campaign-builder auto-login watch link before handing it to the user.",
         };
     }
 }
@@ -593,6 +601,7 @@ export function computeCampaignNavigationStateFromCampaign(campaign, options) {
         watchUrl: {
             urlPresent: watchUrlState.urlPresent,
             direct: watchUrlState.direct,
+            autoLogin: watchUrlState.autoLogin,
             redirectPath: watchUrlState.redirectPath,
         },
         table: {

package/dist/tools/readiness.d.ts

@@ -134,7 +134,8 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         };
         watchUrl: {
             urlPresent: boolean;
-            direct: boolean | undefined;
+            direct: boolean;
+            autoLogin: boolean;
             redirectPath: string | null;
         };
         table: {
@@ -183,7 +184,8 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         };
         watchUrl: {
             urlPresent: boolean;
-            direct: boolean | undefined;
+            direct: boolean;
+            autoLogin: boolean;
             redirectPath: string | null;
         };
         table: {
@@ -234,7 +236,8 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         };
         watchUrl: {
             urlPresent: boolean;
-            direct: boolean | undefined;
+            direct: boolean;
+            autoLogin: boolean;
             redirectPath: string | null;
         };
         table: {

package/dist/tools/rubrics.js

@@ -204,7 +204,7 @@ export const rubricToolDefinitions = [
     },
     {
         name: "save_rubrics",
-        description: "Persist rubric criteria to the campaign. Pass leadScoringRubrics directly to save without drafting. Use update_campaign to enable ICP filtering and change steps.",
+        description: "Persist rubric criteria to the campaign. Pass leadScoringRubrics directly to save without drafting. Saving active rubrics enables ICP filtering on the campaign so the client can continue to Filter Leads.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/watch-url-security.js

@@ -6,9 +6,13 @@ function sanitizeWatchUrlValue(value) {
             if (redirect) {
                 const direct = new URL(decodeURIComponent(redirect), url.origin);
                 const workspaceId = url.searchParams.get("workspaceId");
+                const token = url.searchParams.get("token");
                 if (workspaceId && !direct.searchParams.has("workspaceId")) {
                     direct.searchParams.set("workspaceId", workspaceId);
                 }
+                if (token && !direct.searchParams.has("token")) {
+                    direct.searchParams.set("token", token);
+                }
                 return direct.toString();
             }
         }

package/package.json

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

package/skills/create-campaign/SKILL.md

@@ -134,6 +134,12 @@ claim they ran in parallel and do not surface install status to the customer. In
 chat, call the downstream copy stage `message generation`;
 `message-validation.md` is only an internal proof artifact.
 
+For campaign-attached Signal Discovery sampling, promote/select the exact posts
+with `select_promising_posts` before `fetch_post_engagers` so the user can see
+which posts are being sampled in the watched app. The watch guide should say
+that we are pulling sample engagers from these posts to confirm the ICP is
+actually engaging and the source is viable.
+
 After find-leads returns a lead source and the user approves it, use the same
 registry pattern for the two post-lead branches. The create-campaign-v2 subskill
 calls `get_post_find_leads_scout_registry`, then launches the returned
@@ -159,45 +165,58 @@ linked skill versions, runbooks, npm/package details, repo-local files, VPS or
 browser automation limitations, or local skill files in normal customer-facing
 copy.
 
-## Codex Watch Browser Handoff
-
-When a campaign tool returns `watchUrl`, treat it as an active browser handoff,
-not only a URL to print. A valid handoff link must be a safe direct
-`/campaign-builder/{campaignId}?mode=claude` URL. `create_campaign.watchUrl`,
-`create_campaign({ campaignId }).watchUrl`, and `get_campaign.watchUrl` are all
-acceptable only when they return that direct campaign-builder shape, with
-`workspaceId` used only as a safe routing hint when needed.
-
-In Codex Desktop, when in-app browser control is available, open the returned watch link on the user's behalf. After opening it, inspect the browser-visible campaign state, then explain what the user is seeing before continuing with more campaign tools. Use customer language such as:
-
-```text
-I’ll open the campaign view and keep it in sync as I build.
-```
-
-If browser control is unavailable, provide the watch link without discussing the
-runtime limitation. In off-desktop Codex runs, make the direct watch link easy
-to copy/open, then continue with explicit customer-facing campaign progress and
-`get_campaign_navigation_state` orientation checks.
-Use this fallback shape:
+## Watch Link Handoff
+
+When a campaign tool returns `watchUrl`, treat it as a user-opened watch link.
+A valid handoff link must be a safe direct
+`/campaign-builder/{campaignId}?mode=claude|codex|watch` URL.
+`create_campaign.watchUrl`, `create_campaign({ campaignId }).watchUrl`, and
+`get_campaign.watchUrl` are all acceptable only when they return that direct
+campaign-builder shape, with `workspaceId` used only as a safe routing hint when
+needed.
+
+Do not claim Sellable can force every host to open links in a specific browser.
+The host controls link-click behavior. Do not call Chrome, browser automation,
+shell `open`, Computer Use, or in-app browser-control tools just because a
+watch link exists.
+
+- In Codex Desktop, clicking a URL can open the Codex in-app browser, but that
+  browser is only reliable for unauthenticated/public pages. Sellable campaign
+  watch pages may need a signed-in session. Tell the user to click the link
+  first; if it lands on sign-up/auth, they should open the same link in their
+  regular browser to watch real-time updates.
+- In Claude Code, provide the link and direct the user to open it in their
+  browser. If their Claude Code setup opens links in an in-app/preview browser,
+  that is fine, but do not attempt to open Chrome for them.
+
+Make the direct watch link easy to copy/open, then continue with explicit
+customer-facing campaign progress and `get_campaign_navigation_state`
+orientation checks. Use this fallback shape:
 
 ```text
-Watch link: {watchUrl}
+Watch link: [Open campaign]({watchUrl})
 
-I’ll keep the campaign brief, lead source, and message-review steps explicit
-here as I build.
+Click that link to watch the campaign. If it opens in an in-app browser and asks
+you to sign in, open the same link in your regular browser so you can watch
+real-time updates from your signed-in session. I’ll keep the brief, lead source,
+and message-review steps explicit here as I build.
 ```
 
-If opening the watch link lands on an auth, 404, permission, blank, or visible
-error state, report only what is visible, recover a fresh watch link once with
-`create_campaign({ campaignId })` or `get_campaign`, and try that link. Do not
-claim the browser was opened, inspected, or synchronized unless the visible
-browser state was actually observed. Do not claim the browser was opened unless
-it was opened and observed.
+If the user reports that the watch link lands on auth, 404, permission, blank,
+or an error state, recover a fresh watch link once with
+`create_campaign({ campaignId })` or `get_campaign`, then print the recovered
+link. Do not claim the browser was opened, inspected, or synchronized.
 
 After every `update_campaign({ campaignId, currentStep })`, use
 `get_campaign_navigation_state` when available as a compact orientation check:
-match the browser-visible step to the saved campaign state, explain the current
-state in one sentence, and only then continue. Sender selection belongs at Settings after message approval and 10-row validation. After message validation, use Settings to help the user connect or select a LinkedIn sender. Explain Slack reply review before launch. After sender selection, attach the recommended sequence and move the watched UI to Send. Do not start the campaign or trigger a live send unless the user explicitly confirms that launch action outside UAT.
+match the expected watch-link step to the saved campaign state, explain the
+current state in one sentence, and only then continue. Sender selection belongs
+at Settings after message approval and 10-row validation. After message
+validation, use Settings to help the user connect or select a LinkedIn sender.
+Explain Slack reply review before launch. After sender selection, attach the
+recommended sequence and move the watched UI to Send. Do not start the campaign
+or trigger a live send unless the user explicitly confirms that launch action
+outside UAT.
 
 ## Names To Use
 

package/skills/create-campaign-v2/SKILL.md

@@ -805,7 +805,9 @@ Required behavior:
   `lead-review.md` focused on source evidence, not host-agent availability.
   - Branch A: LinkedIn Engagement / active LinkedIn posts (internal provider:
     Signals / `signal-discovery`). Search relevant keyword lanes, review
-    finalist posts, fetch top-post engagers, and estimate warm-fit volume.
+    finalist posts, promote the sampled posts with `select_promising_posts`
+    before fetching engagers when a campaign shell exists, fetch top-post
+    engagers, and estimate warm-fit volume.
   - Branch B: Sales Nav / title + company filters. Run preview filters, inspect
     preview rows, and estimate scalable-fit volume.
   - Branch C: Prospeo Contact / domains only when the campaign has a
@@ -1019,7 +1021,9 @@ lower confidence instead of presenting a precise estimate.
 
 For Signals, default to sampling a few promising posts first rather than trying
 to prove the entire source can scale before the user sees evidence. Pick 3-5
-fresh, high-density posts when available, sample engagers, show fit rate, then
+fresh, high-density posts when available. In campaign-attached watch runs,
+promote those posts with `select_promising_posts` before sampling so the user
+sees which posts are being tested. Then sample engagers, show fit rate, and
 state how many additional posts could be added/scraped if that first sample is
 good but volume is low.
 

package/skills/create-campaign-v2/core/flow.v2.json

@@ -330,11 +330,12 @@
             "campaignBrief"
           ],
           "watchUrlSource": "create_campaign.watchUrl",
-          "requiredWatchUrlShape": "direct /campaign-builder/{campaignId}?mode={claude|codex} watch URL",
+          "requiredWatchUrlShape": "direct /campaign-builder/{campaignId}?mode={claude|codex} watch URL with token auto-login and workspace routing",
           "codexBrowserHandoff": {
-            "openWhenAvailable": true,
-            "inspectBeforeContinuing": true,
-            "explainVisibleStateBeforeContinuing": true,
+            "openWhenAvailable": false,
+            "printWatchLinkOnly": true,
+            "tellUserCommandEnterOrClick": true,
+            "mustNotUseBrowserAutomation": true,
             "fallbackMustNotClaimInspection": true,
             "recoverFreshSignedLinkOnceOnOpenFailure": true
           },
@@ -540,7 +541,7 @@
             "uploadedDomains": "prospeo"
           },
           "when": "before_background_source_scouts",
-          "rule": "Choose the likely primary visible source lane from source intake, brief preference, or the best first lane the main thread will actually search. Send watchNarration with stage find-leads that says what search was tried or is being tried next, what sample is being checked, and why it helps this campaign. Do this before waiting on background scouts so watch mode never sits on only Pick Provider while source work happens elsewhere."
+          "rule": "Choose the likely primary visible source lane from source intake, brief preference, or the best first lane the main thread will actually search. Send watchNarration with stage find-leads that says what search was tried or is being tried next, what sample is being checked, and why it helps this campaign. For Signal Discovery sampling, promote/select the posts with select_promising_posts before fetch_post_engagers so the watched table shows the exact posts being sampled; the guide copy should say Codex is pulling sample engagers from these posts to confirm the ICP is actually engaging and the source is viable. Do this before waiting on background scouts so watch mode never sits on only Pick Provider while source work happens elsewhere."
         },
         {
           "action": "run_first_campaign_attached_source_search",

package/skills/create-campaign-v2/references/watch-guide-narration.md

@@ -67,9 +67,9 @@ Signal Discovery:
 ```json
 {
   "stage": "find-leads",
-  "headline": "Testing Signal Discovery",
-  "visibleState": "You are watching Signal Discovery search posts about Claude Code and GTM automation.",
-  "agentIntent": "Codex is sampling engagers to see if they match the founder/operator campaign brief.",
+  "headline": "Testing warm LinkedIn activity",
+  "visibleState": "The promoted posts are the ones being sampled now.",
+  "agentIntent": "Codex is pulling sample engagers from these posts to confirm the ICP is actually engaging and that this source is viable.",
   "nextAction": "Review batch"
 }
 ```

package/skills/create-campaign-v2/references/watch-link-handoff.md

@@ -11,12 +11,13 @@ gating, and handoff read campaign state first.
 
 ## Plumbing Reuse
 
-`create_campaign` already returns a safe direct campaign-builder `watchUrl` on
-the response (`CampaignDetail.watchUrl` in
-`mcp/sellable/src/tools/campaigns.ts`). V2 does NOT mint a new token, does NOT call
-a different route, and does NOT construct the URL locally. Capture whatever
-`watchUrl` the existing tool returns and surface it verbatim. The link must
-land on the campaign builder without exposing token secrets in the MCP result.
+`create_campaign` already returns a direct campaign-builder `watchUrl` on the
+response (`CampaignDetail.watchUrl` in `mcp/sellable/src/tools/campaigns.ts`).
+The URL includes the auth token and workspace routing needed for browser
+auto-login, then the app exchanges the token through `/auth/continue` and
+cleans it from the browser URL. V2 does NOT mint a new token, does NOT call a
+different route, and does NOT construct the URL locally. Capture whatever
+`watchUrl` the existing tool returns and surface it verbatim.
 
 ## Shell-First Link
 
@@ -37,7 +38,13 @@ You can watch the lead source, filters, and messages fill in from here.
 
 No leads import and nothing sends yet.
 
-Watch link: {watchUrl}
+Watch link: [Open campaign]({watchUrl})
+
+Click that link to watch the campaign. If it opens in an in-app browser and asks
+you to sign in, open the same link in your regular browser so you can watch
+real-time updates from your signed-in session.
+
+Command-Enter or click that link to watch it in Sellable.
 
 Cool, let's find leads.
 ```
@@ -55,6 +62,25 @@ clear:
 - the brief is already visible in the campaign
 - import, sequence, and start are still blocked
 
+## Browser Choice
+
+Do not claim Sellable can force the user's host to open links in a specific
+browser. The host controls link-click behavior.
+Do not call Chrome, browser automation, shell `open`, Computer Use, or in-app
+browser-control tools just because a watch link exists.
+
+- Codex Desktop URL clicks can open the Codex in-app browser, but that browser
+  is only reliable for public or unauthenticated pages. Sellable campaign watch
+  pages depend on a signed-in session, so if the in-app browser lands on
+  sign-up/auth, tell the user to open the same link in their regular browser to
+  watch real-time updates.
+- Claude Code should provide the link and direct the user to open it in their
+  browser. If the user's Claude Code setup opens links in an in-app/preview
+  browser, that is fine, but do not attempt to open Chrome for them.
+
+Surface the link as a normal Markdown link and continue with explicit progress
+updates in chat.
+
 If shell creation fails or the response is missing `watchUrl`, stop and surface
 the error. Do not continue into campaignless source scouting in the active
 shell-first flow.
@@ -93,7 +119,9 @@ cached or reconstructed URL.
 ## Hard Rules
 
 - Never fabricate or reconstruct the URL locally.
-- The watch link must be a safe direct campaign-builder URL.
+- The watch link must be a direct campaign-builder URL with token auto-login.
+- Do not call browser-opening tools, shell `open`, Computer Use, or in-app
+  browser automation; the user opens the link when they want to watch.
 - Missing `watchUrl` is an error, not a silent skip.
 - The first watch link must be shown only after the v1 brief is on the campaign.
 - A watch link is not approval to import, attach sequence, or start.

package/skills/providers/signal-discovery.md

@@ -94,6 +94,8 @@ Use conservative logic:
 1. Start from recent strong-post inventory and sample quality, not raw total post count.
 2. If the lane looks promising, sample real engagers before claiming a reachable-lead estimate:
    - choose 1-2 promising posts
+   - in campaign-attached runs, call `select_promising_posts` first to promote
+     those posts in the watched Signal Discovery UI before sampling engagers
    - call `fetch_post_engagers`
    - fetch only a representative first sample, not a full scrape
    - default to `limit: 25` for one post or `limit: 20` per post when checking two posts
@@ -325,6 +327,11 @@ Select the best posts to scrape AND provide headline ICP criteria.
 Use `selectionTarget` and `recommendedPostIds` returned by `search_signals`
 (default selectionTarget is 3).
 
+For campaign-attached viability sampling, this is also the promote step: call it
+before `fetch_post_engagers` so the user sees the exact posts being sampled in
+the watched Signal Discovery table. Use `selectionMode: "replace"` for the first
+sample set unless the user explicitly wants to add to existing promoted posts.
+
 ```json
 select_promising_posts({
   "campaignOfferId": "cmp_xxx",