@sellable/mcp 0.1.94 → 0.1.95

package/dist/tools/context.d.ts

@@ -68,6 +68,22 @@ export declare function getCampaignContext(input: GetCampaignContextInput): Prom
         expectedHeadlessStep: string | null;
         headlessCurrentStep: string | null;
         uiStep: string | null;
+        orientation: {
+            visibleStep: string | null;
+            browserStepLabel: string;
+            customerSummary: string;
+            nextVisibleMilestone: string;
+            blockedReason: string | null;
+            agentGuidance: string;
+            browserCheckpoint: string;
+            senderSelectionAllowed: boolean;
+            safeToAskSender: boolean;
+        };
+        watchUrl: {
+            urlPresent: boolean;
+            signed: boolean;
+            redirectPath: string | null;
+        };
         table: {
             workflowTableId: string | null;
             checked: boolean;

package/dist/tools/context.js

@@ -165,6 +165,22 @@ export function markCampaignContextDirty(campaignId, reason) {
             expectedHeadlessStep: "create-offer",
             headlessCurrentStep: null,
             uiStep: "plan",
+            orientation: {
+                visibleStep: "plan",
+                browserStepLabel: "Campaign brief",
+                customerSummary: "The campaign view is waiting for saved campaign context.",
+                nextVisibleMilestone: "Lead source search",
+                blockedReason: "Missing campaignContextNotLoaded",
+                agentGuidance: "Refresh campaign navigation state before describing the browser.",
+                browserCheckpoint: "brief",
+                senderSelectionAllowed: false,
+                safeToAskSender: false,
+            },
+            watchUrl: {
+                urlPresent: false,
+                signed: false,
+                redirectPath: null,
+            },
             table: {
                 workflowTableId: null,
                 checked: false,

package/dist/tools/navigation.d.ts

@@ -25,6 +25,7 @@ export type CampaignOfferNavigation = {
     campaignStatus?: string | null;
     status?: string | null;
     currentStep?: string | null;
+    watchUrl?: string | null;
 };
 type NavigationDebugPayload = Record<string, unknown>;
 export declare function logNavigationDebug(event: string, payload?: NavigationDebugPayload, campaignId?: string | null): void;
@@ -67,6 +68,22 @@ export declare function computeCampaignNavigationStateFromCampaign(campaign: Cam
     expectedHeadlessStep: string | null;
     headlessCurrentStep: string | null;
     uiStep: string | null;
+    orientation: {
+        visibleStep: string | null;
+        browserStepLabel: string;
+        customerSummary: string;
+        nextVisibleMilestone: string;
+        blockedReason: string | null;
+        agentGuidance: string;
+        browserCheckpoint: string;
+        senderSelectionAllowed: boolean;
+        safeToAskSender: boolean;
+    };
+    watchUrl: {
+        urlPresent: boolean;
+        signed: boolean;
+        redirectPath: string | null;
+    };
     table: {
         workflowTableId: string | null;
         checked: boolean;
@@ -95,6 +112,22 @@ export declare function getCampaignNavigationState(input: GetCampaignNavigationS
     expectedHeadlessStep: string | null;
     headlessCurrentStep: string | null;
     uiStep: string | null;
+    orientation: {
+        visibleStep: string | null;
+        browserStepLabel: string;
+        customerSummary: string;
+        nextVisibleMilestone: string;
+        blockedReason: string | null;
+        agentGuidance: string;
+        browserCheckpoint: string;
+        senderSelectionAllowed: boolean;
+        safeToAskSender: boolean;
+    };
+    watchUrl: {
+        urlPresent: boolean;
+        signed: boolean;
+        redirectPath: string | null;
+    };
     table: {
         workflowTableId: string | null;
         checked: boolean;

package/dist/tools/navigation.js

@@ -301,6 +301,120 @@ function mapHeadlessToUiStep(step) {
     }
     return null;
 }
+function describeVisibleStep(step) {
+    switch (step) {
+        case "plan":
+            return {
+                label: "Campaign brief",
+                summary: "The campaign brief is visible in the campaign view.",
+                nextMilestone: "Lead source search",
+                guidance: "Confirm the browser-visible campaign state before moving to lead sourcing.",
+                checkpoint: "brief",
+            };
+        case "pick-provider":
+        case "contact-search":
+        case "signal-discovery":
+            return {
+                label: "Lead sourcing",
+                summary: "Lead source selection or search is visible.",
+                nextMilestone: "Lead preview",
+                guidance: "Explain the selected lead-source lane and visible search state before continuing.",
+                checkpoint: "lead-source",
+            };
+        case "leads":
+            return {
+                label: "Lead import",
+                summary: "The lead preview or imported review batch is visible.",
+                nextMilestone: "Fit filtering and message review",
+                guidance: "Confirm the browser-visible campaign state and row batch before filter/message work.",
+                checkpoint: "import",
+            };
+        case "filter-choice":
+        case "filter-rules":
+        case "filter-leads":
+            return {
+                label: "Fit filtering",
+                summary: "Fit filtering or sample validation is visible.",
+                nextMilestone: "Message review or validation",
+                guidance: "Explain the visible filter or validation state and wait for the next approved step.",
+                checkpoint: "filters",
+            };
+        case "messages":
+            return {
+                label: "Message review",
+                summary: "Message review or generation is visible.",
+                nextMilestone: "10-row validation",
+                guidance: "Explain the visible message state before asking for approval or validation.",
+                checkpoint: "messages",
+            };
+        case "settings":
+            return {
+                label: "Settings",
+                summary: "Settings is visible. Sender selection belongs here.",
+                nextMilestone: "Safe sender selection",
+                guidance: "Select a safe connected sender here only; stop before sequence/start/live send in UAT.",
+                checkpoint: "settings",
+            };
+        case "sequence":
+            return {
+                label: "Sequence setup",
+                summary: "Sequence setup is visible.",
+                nextMilestone: "Explicit launch approval",
+                guidance: "Do not attach or change sequence state during watch UAT unless explicitly approved.",
+                checkpoint: "sequence",
+            };
+        case "send":
+            return {
+                label: "Send review",
+                summary: "Send review or running status is visible.",
+                nextMilestone: "Explicit launch approval",
+                guidance: "Do not start the campaign or trigger live send without explicit user confirmation.",
+                checkpoint: "send",
+            };
+        default:
+            return {
+                label: "Campaign view",
+                summary: "The campaign view is loading or waiting for the next saved step.",
+                nextMilestone: "Next saved campaign step",
+                guidance: "Inspect the browser-visible campaign state before continuing with more tools.",
+                checkpoint: "unknown",
+            };
+    }
+}
+function parseSignedWatchUrl(watchUrl, campaignId) {
+    if (!watchUrl) {
+        return {
+            urlPresent: false,
+            signed: false,
+            redirectPath: null,
+            warning: null,
+        };
+    }
+    try {
+        const url = new URL(watchUrl);
+        const redirect = url.searchParams.get("redirect");
+        const decodedRedirect = redirect ? decodeURIComponent(redirect) : null;
+        const signed = url.pathname === "/auth/continue" &&
+            Boolean(url.searchParams.get("token")) &&
+            decodedRedirect === `/campaign-builder/${campaignId}?mode=claude`;
+        return {
+            urlPresent: true,
+            signed,
+            redirectPath: decodedRedirect,
+            warning: signed
+                ? null
+                : "Watch URL is not a signed /auth/continue watch link for /campaign-builder/{campaignId}?mode=claude.",
+        };
+    }
+    catch {
+        return {
+            urlPresent: true,
+            signed: false,
+            redirectPath: null,
+            warning: "Watch URL is malformed; recover a fresh signed /auth/continue watch link before browser handoff.",
+        };
+    }
+}
 export const navigationToolDefinitions = [
     {
         name: "get_campaign_navigation_state",
@@ -401,30 +515,49 @@ export function computeCampaignNavigationStateFromCampaign(campaign, options) {
     if (!blockedAt && evaluateTailState) {
         computedStep = isRunningCampaign(campaign) ? "running" : "send";
     }
-    const expectedHeadlessStep = computedStep === "campaign-created"
+    const stepForHeadless = blockedAt ?? computedStep;
+    const expectedHeadlessStep = stepForHeadless === "campaign-created"
         ? "create-offer"
-        : computedStep === "provider-search"
+        : stepForHeadless === "provider-search"
             ? providerConfig?.currentStep || campaign.leadSourceProvider || null
-            : computedStep === "filter-rules"
+            : stepForHeadless === "filter-rules"
                 ? "create-icp-rubric"
-                : computedStep === "messages"
+                : stepForHeadless === "messages"
                     ? "messages"
-                    : computedStep === "settings"
+                    : stepForHeadless === "settings"
                         ? "settings"
-                        : computedStep === "sequence"
+                        : stepForHeadless === "sequence"
                             ? "sequence"
-                            : computedStep === "running"
+                            : stepForHeadless === "running"
                                 ? "running"
-                                : computedStep;
+                                : stepForHeadless;
+    const currentUiStep = mapHeadlessToUiStep(campaign.currentStep);
+    const expectedUiStep = mapHeadlessToUiStep(expectedHeadlessStep);
     const stepAligned = !campaign.currentStep || !expectedHeadlessStep
         ? null
-        : campaign.currentStep === expectedHeadlessStep;
+        : campaign.currentStep === expectedHeadlessStep ||
+            (currentUiStep !== null && currentUiStep === expectedUiStep);
     if (stepAligned === false && campaign.currentStep && expectedHeadlessStep) {
         warnings.push(`Headless step mismatch: expected "${expectedHeadlessStep}" but campaign.currentStep is "${campaign.currentStep}".`);
     }
     if (!providerConfig && campaign.leadSourceProvider) {
         warnings.push(`Provider config not found for "${campaign.leadSourceProvider}".`);
     }
+    const uiStep = currentUiStep;
+    const orientationStep = uiStep || mapHeadlessToUiStep(expectedHeadlessStep);
+    const orientationSource = isRunningCampaign(campaign)
+        ? {
+            label: "Running campaign",
+            summary: "The campaign is running and the send review is visible.",
+            nextMilestone: "Explicit launch approval",
+            guidance: "Confirm the browser-visible campaign state before describing the running status.",
+            checkpoint: "send",
+        }
+        : describeVisibleStep(orientationStep);
+    const watchUrlState = parseSignedWatchUrl(campaign.watchUrl, campaign.id);
+    if (watchUrlState.warning) {
+        warnings.push(watchUrlState.warning);
+    }
     const result = {
         campaignId: campaign.id,
         computedStep,
@@ -432,7 +565,23 @@ export function computeCampaignNavigationStateFromCampaign(campaign, options) {
         missing,
         expectedHeadlessStep,
         headlessCurrentStep: campaign.currentStep ?? null,
-        uiStep: mapHeadlessToUiStep(campaign.currentStep),
+        uiStep,
+        orientation: {
+            visibleStep: orientationStep,
+            browserStepLabel: orientationSource.label,
+            customerSummary: orientationSource.summary,
+            nextVisibleMilestone: orientationSource.nextMilestone,
+            blockedReason: missing.length > 0 ? `Missing ${missing.join(", ")}` : null,
+            agentGuidance: orientationSource.guidance,
+            browserCheckpoint: orientationSource.checkpoint,
+            senderSelectionAllowed: orientationStep === "settings",
+            safeToAskSender: orientationStep === "settings",
+        },
+        watchUrl: {
+            urlPresent: watchUrlState.urlPresent,
+            signed: watchUrlState.signed,
+            redirectPath: watchUrlState.redirectPath,
+        },
         table: {
             workflowTableId: campaign.workflowTableId ?? null,
             checked: options.tableChecked,
@@ -461,6 +610,8 @@ export function computeCampaignNavigationStateFromCampaign(campaign, options) {
         expectedHeadlessStep: result.expectedHeadlessStep,
         headlessCurrentStep: result.headlessCurrentStep,
         uiStep: result.uiStep,
+        orientation: result.orientation,
+        watchUrl: result.watchUrl,
         table: result.table,
         context: result.context,
         warnings: result.warnings,

package/dist/tools/readiness.d.ts

@@ -121,6 +121,22 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         expectedHeadlessStep: string | null;
         headlessCurrentStep: string | null;
         uiStep: string | null;
+        orientation: {
+            visibleStep: string | null;
+            browserStepLabel: string;
+            customerSummary: string;
+            nextVisibleMilestone: string;
+            blockedReason: string | null;
+            agentGuidance: string;
+            browserCheckpoint: string;
+            senderSelectionAllowed: boolean;
+            safeToAskSender: boolean;
+        };
+        watchUrl: {
+            urlPresent: boolean;
+            signed: boolean;
+            redirectPath: string | null;
+        };
         table: {
             workflowTableId: string | null;
             checked: boolean;
@@ -154,6 +170,22 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         expectedHeadlessStep: string | null;
         headlessCurrentStep: string | null;
         uiStep: string | null;
+        orientation: {
+            visibleStep: string | null;
+            browserStepLabel: string;
+            customerSummary: string;
+            nextVisibleMilestone: string;
+            blockedReason: string | null;
+            agentGuidance: string;
+            browserCheckpoint: string;
+            senderSelectionAllowed: boolean;
+            safeToAskSender: boolean;
+        };
+        watchUrl: {
+            urlPresent: boolean;
+            signed: boolean;
+            redirectPath: string | null;
+        };
         table: {
             workflowTableId: string | null;
             checked: boolean;
@@ -189,6 +221,22 @@ export declare function waitForCampaignTableReady(input: WaitForCampaignTableRea
         expectedHeadlessStep: string | null;
         headlessCurrentStep: string | null;
         uiStep: string | null;
+        orientation: {
+            visibleStep: string | null;
+            browserStepLabel: string;
+            customerSummary: string;
+            nextVisibleMilestone: string;
+            blockedReason: string | null;
+            agentGuidance: string;
+            browserCheckpoint: string;
+            senderSelectionAllowed: boolean;
+            safeToAskSender: boolean;
+        };
+        watchUrl: {
+            urlPresent: boolean;
+            signed: boolean;
+            redirectPath: string | null;
+        };
         table: {
             workflowTableId: string | null;
             checked: boolean;

package/package.json

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

package/skills/create-campaign/SKILL.md

@@ -158,6 +158,45 @@ Never mention MCP namespaces, prompt chunking, plugin cache paths, missing
 linked skill versions, runbooks, 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 signed
+`/auth/continue?token=...&redirect=/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 signed
+shape.
+
+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, say so briefly and provide the watch link.
+In VPS or other off-desktop Codex runs, this fallback is the expected handoff for
+the local headed watch observer: make the signed link easy to copy/open, then
+continue with explicit chat progress and `get_campaign_navigation_state`
+orientation checks.
+Use this fallback shape:
+
+```text
+I can’t inspect the campaign browser from this Codex session, so I’ll keep the
+chat steps explicit here. Watch link: {watchUrl}
+```
+
+If opening the watch link lands on an auth, 404, permission, blank, or visible
+error state, report only what is visible, recover a fresh signed 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.
+
+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. Do not attach a sequence, start the campaign, or trigger a live send unless the user explicitly confirms that launch action outside UAT.
+
 ## Names To Use
 
 Use these exact public names so Claude Code and Codex do not drift:

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

@@ -100,7 +100,7 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   `awaiting-user-greenlight` for Settings. Do not advance `currentStep` backward.
 - After the shell is minted, normal resume paths read the CampaignOffer first.
   Use debug files to explain or reconstruct work, not to decide whether a
-  post-mint gate is allowed. Validation/debug artifacts are not durable campaign
+  post-mint gate is allowed. validation/debug artifacts are not durable campaign
   state.
 - The campaign shell may receive setup state before import: approved brief text,
   campaign-attached provider searches/selections, the bounded review-batch

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

@@ -307,6 +307,14 @@
             "campaignBrief"
           ],
           "watchUrlSource": "create_campaign.watchUrl",
+          "requiredWatchUrlShape": "signed /auth/continue?token=...&redirect=/campaign-builder/{campaignId}?mode=claude",
+          "codexBrowserHandoff": {
+            "openWhenAvailable": true,
+            "inspectBeforeContinuing": true,
+            "explainVisibleStateBeforeContinuing": true,
+            "fallbackMustNotClaimInspection": true,
+            "recoverFreshSignedLinkOnceOnOpenFailure": true
+          },
           "immediateNextMainChatLine": "Cool, let's find leads."
         }
       ],
@@ -1415,13 +1423,26 @@
           "when": "after_message_approved_before_import",
           "fields": [
             "campaignBrief with ## Approved Message Template, Token Fill Rules, Token Fill Examples",
-            "currentStep:validate-sample",
             "useMessagingTemplate:true"
           ],
           "requiredBeforeImport": false,
           "onFailure": "stop_before_import_or_enrichment",
           "requiredBeforeCascade": true,
           "writesCampaignState": "campaignBrief.Approved Message Template"
+        },
+        {
+          "action": "advance_watch_to_validation_after_message_approval",
+          "tool": "update_campaign",
+          "requires": [
+            "campaignId",
+            "message-review-decision.md"
+          ],
+          "requiredValues": {
+            "currentStep": "validate-sample"
+          },
+          "when": "after_update_campaign_brief_succeeds",
+          "requiredBeforeCascade": true,
+          "writesCampaignState": "currentStep:validate-sample"
         }
       ],
       "requiredArtifacts": [
@@ -1439,7 +1460,8 @@
         "AskUserQuestion",
         "request_user_input",
         "get_subskill_prompt",
-        "update_campaign_brief"
+        "update_campaign_brief",
+        "update_campaign"
       ],
       "doNotAllow": [
         "create_campaign",