@sellable/mcp 0.1.557 → 0.1.558

package/README.md

@@ -16,9 +16,8 @@ Each message gets 5+ minutes of Claude attention with deep research - no other t
 
 ### Prompt Source Of Truth
 
-There are nine public Sellable entrypoints shared across hosts:
+There are eight public Sellable entrypoints shared across hosts:
 
-- `sellable:find-leads`
 - `sellable:create-campaign`
 - `sellable:create-ab-test`
 - `sellable:create-evergreen-campaigns`
@@ -34,11 +33,6 @@ the approval-gated workflow from:
 
 - `mcp/sellable/skills/create-campaign-v2/SKILL.md`
 
-The find-leads public wrapper builds a live exportable source list without a
-campaign and loads its durable approval-gated workflow from:
-
-- `mcp/sellable/skills/find-leads-v2/SKILL.md`
-
 The create-ab-test public wrapper prepares clean A/B split lead lists and
 review-copy campaigns from:
 
@@ -211,7 +205,7 @@ thread and select `Sellable Create Campaign`, `Sellable Create A/B Test`,
 `Sellable Create Evergreen Campaigns`, `Sellable Foundation`,
 `Sellable Content`, `Sellable Create Post`, `Sellable Refresh Sender Engagement`,
 or `Sellable Refill Sends`; or invoke
-`$sellable:find-leads`, `$sellable:create-campaign`, `$sellable:create-ab-test`,
+`$sellable:create-campaign`, `$sellable:create-ab-test`,
 `$sellable:create-evergreen-campaigns`, `$sellable:foundation`,
 `$sellable:content`, `$sellable:create-post`,
 `$sellable:refresh-sender-engagement`, or `$sellable:refill-sends`. If the app still says
@@ -226,7 +220,6 @@ the Sellable MCP tools for Codex Desktop.
 Use these names consistently:
 
 - Claude Code command: `/sellable:create-campaign`
-- Claude Code command: `/sellable:find-leads`
 - Claude Code command: `/sellable:create-ab-test`
 - Claude Code command: `/sellable:create-evergreen-campaigns`
 - Claude Code command: `/sellable:foundation`
@@ -235,7 +228,6 @@ Use these names consistently:
 - Claude Code command: `/sellable:refresh-sender-engagement`
 - Claude Code command: `/sellable:refill-sends`
 - Codex command: `$sellable:create-campaign`
-- Codex command: `$sellable:find-leads`
 - Codex command: `$sellable:create-ab-test`
 - Codex command: `$sellable:create-evergreen-campaigns`
 - Codex command: `$sellable:foundation`
@@ -245,7 +237,6 @@ Use these names consistently:
 - Codex command: `$sellable:refill-sends`
 - Codex Desktop plugin: `sellable@sellable`
 - Codex visible skill: `Sellable Create Campaign`
-- Codex visible skill: `Sellable Find Leads`
 - Codex visible skill: `Sellable Create A/B Test`
 - Codex visible skill: `Sellable Create Evergreen Campaigns`
 - Codex visible skill: `Sellable Foundation`
@@ -254,7 +245,6 @@ Use these names consistently:
 - Codex visible skill: `Sellable Refresh Sender Engagement`
 - Codex visible skill: `Sellable Refill Sends`
 - Codex skill frontmatter name: `create-campaign`
-- Codex skill frontmatter name: `find-leads`
 - Codex skill frontmatter name: `create-ab-test`
 - Codex skill frontmatter name: `create-evergreen-campaigns`
 - Codex skill frontmatter name: `foundation`
@@ -264,7 +254,6 @@ Use these names consistently:
 - Codex skill frontmatter name: `refill-sends`
 - MCP server name: `sellable`
 - Internal workflow prompt: `create-campaign-v2`
-- Internal workflow prompt: `find-leads-v2`
 - Internal workflow prompt: `refill-sends-workflow`
 - Internal/backward-compatible memory prompt: `interview`
 

package/agents/registry.json

@@ -26,8 +26,8 @@
       "ownership": "message strategy, proof inventory, token rules, skeptical-prospect review, and selected winner only",
       "codex": {
         "description": "Message Drafting worker for campaign-backed template proposals after confirm_lead_list imports a non-empty bounded review batch.",
-        "model": "gpt-5.5",
-        "modelReasoningEffort": "xhigh",
+        "model": "gpt-5.6-sol",
+        "modelReasoningEffort": "high",
         "sandboxMode": "read-only",
         "nicknameCandidates": [
           "Message Drafting",

package/dist/api.js

@@ -3,7 +3,7 @@ import { mkdir, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { getConfig, getConfigPath } from "./auth.js";
+import { getConfig, getConfigPath, getEffectiveConfiguredWorkspaceId, resolveWorkspaceIdForRequest, } from "./auth.js";
 export class SellableApiError extends Error {
     status;
     body;
@@ -42,9 +42,12 @@ export class SellableApi {
         // Re-read config on every request so workspace switches take effect immediately
         const config = getConfig();
         const url = `${config.apiUrl}${path}`;
-        const workspaceId = options && Object.prototype.hasOwnProperty.call(options, "workspaceId")
+        const requestedWorkspaceId = options && Object.prototype.hasOwnProperty.call(options, "workspaceId")
             ? options.workspaceId
-            : config.activeWorkspaceId || config.workspaceId || null;
+            : getEffectiveConfiguredWorkspaceId(config);
+        const workspaceId = options && Object.prototype.hasOwnProperty.call(options, "workspaceId")
+            ? resolveWorkspaceIdForRequest(requestedWorkspaceId, `${method} ${path}`)
+            : requestedWorkspaceId;
         const response = await fetch(url, {
             method,
             headers: {

package/dist/auth.d.ts

@@ -40,6 +40,12 @@ export type SkillState = {
 export declare function setConfigFile(fileName: string): void;
 export declare function getResolvedConfigsDir(): string | null;
 export declare function getConfigPath(): string;
+export declare function getLockedWorkspaceId(): string | null;
+export declare function isWorkspaceLockRequired(): boolean;
+export declare function workspaceLockRequiredMessage(action?: string): string;
+export declare function assertWorkspaceLockSatisfied(action?: string): void;
+export declare function getEffectiveConfiguredWorkspaceId(config: Pick<SellableConfig, "activeWorkspaceId" | "workspaceId">): string | null;
+export declare function resolveWorkspaceIdForRequest(requestedWorkspaceId: string | null | undefined, action?: string): string | null;
 export declare function getConfig(): SellableConfig;
 export declare function updateActiveWorkspace(params: {
     workspaceId: string;

package/dist/auth.js

@@ -2,6 +2,8 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 const DEFAULT_API_URL = "https://app.sellable.dev";
+const WORKSPACE_LOCK_ENV = "SELLABLE_LOCK_WORKSPACE_ID";
+const REQUIRE_WORKSPACE_LOCK_ENV = "SELLABLE_REQUIRE_WORKSPACE_LOCK";
 // No caching — re-read config on every call so token/workspace changes
 // made by the LLM (editing sellable.json) take effect immediately
 // without requiring an MCP server restart.
@@ -85,6 +87,44 @@ function normalizeConfig(raw) {
         apiUrl: raw.apiUrl || DEFAULT_API_URL,
     };
 }
+export function getLockedWorkspaceId() {
+    const value = process.env[WORKSPACE_LOCK_ENV]?.trim();
+    return value || null;
+}
+export function isWorkspaceLockRequired() {
+    const value = process.env[REQUIRE_WORKSPACE_LOCK_ENV]?.trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes";
+}
+export function workspaceLockRequiredMessage(action = "Sellable request") {
+    return (`Workspace lock required: ${action} cannot run because ` +
+        `${REQUIRE_WORKSPACE_LOCK_ENV}=1 but ${WORKSPACE_LOCK_ENV} is missing. ` +
+        "Ask the sellable-admin profile to provision this customer profile with an approved customer workspace.");
+}
+export function assertWorkspaceLockSatisfied(action = "Sellable request") {
+    if (isWorkspaceLockRequired() && !getLockedWorkspaceId()) {
+        throw new Error(workspaceLockRequiredMessage(action));
+    }
+}
+function normalizeWorkspaceId(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+export function getEffectiveConfiguredWorkspaceId(config) {
+    assertWorkspaceLockSatisfied("workspace resolution");
+    return (getLockedWorkspaceId() ||
+        normalizeWorkspaceId(config.activeWorkspaceId) ||
+        normalizeWorkspaceId(config.workspaceId));
+}
+export function resolveWorkspaceIdForRequest(requestedWorkspaceId, action = "Sellable request") {
+    assertWorkspaceLockSatisfied(action);
+    const lockedWorkspaceId = getLockedWorkspaceId();
+    const requested = normalizeWorkspaceId(requestedWorkspaceId);
+    if (!lockedWorkspaceId)
+        return requested;
+    if (requested && requested !== lockedWorkspaceId) {
+        throw new Error(`Workspace lock violation: ${action} requested workspace ${requested}, but this profile is locked to ${lockedWorkspaceId}.`);
+    }
+    return lockedWorkspaceId;
+}
 export function getConfig() {
     // Config cache removed 2026-05-04: we always re-read from disk so
     // workspace switches (set_active_workspace) take effect immediately
@@ -139,6 +179,7 @@ export function getConfig() {
     }
 }
 export function updateActiveWorkspace(params) {
+    resolveWorkspaceIdForRequest(params.workspaceId, "set_active_workspace");
     const configPath = getConfigPath();
     const configDir = path.dirname(configPath);
     if (!fs.existsSync(configDir)) {
@@ -226,6 +267,7 @@ function writeRawConfigFile(configPath, raw) {
  * new config without an MCP server restart.
  */
 export function writeNewConfig(opts) {
+    resolveWorkspaceIdForRequest(opts.activeWorkspaceId, "write Sellable auth config");
     const configPath = getConfigWritePath();
     let raw = {};
     if (fs.existsSync(configPath)) {
@@ -283,7 +325,7 @@ function getActiveEnvConfigRef(raw) {
 }
 export function getEngageState() {
     const config = getConfig();
-    const workspaceId = config.activeWorkspaceId || config.workspaceId || null;
+    const workspaceId = getEffectiveConfiguredWorkspaceId(config);
     if (!workspaceId) {
         return { activeWorkspaceId: null, state: null };
     }
@@ -294,7 +336,7 @@ export function updateEngageState(patch) {
     const { configPath, raw } = readRawConfigFile();
     const { envConfig, set } = getActiveEnvConfigRef(raw);
     const normalized = normalizeConfig(envConfig);
-    const workspaceId = normalized.activeWorkspaceId || normalized.workspaceId || null;
+    const workspaceId = getEffectiveConfiguredWorkspaceId(normalized);
     if (!workspaceId) {
         throw new Error("No active workspace selected. Run list_workspaces then set_active_workspace.");
     }

package/dist/refill-contract.d.ts

@@ -0,0 +1,157 @@
+export declare const REFILL_CONTRACT_VERSION: "2.0.0";
+export declare const REFILL_CONTRACT_CACHE_VERSION: "refill-contract-v1";
+export declare const REFILL_CONTRACT_SUPPORTED_MAJOR: 2;
+export declare const REFILL_CONTRACT_ERROR_CODES: readonly ["refill_contract_not_implemented", "unsupported_refill_contract_major", "refill_contract_hash_mismatch", "refill_contract_semantic_mismatch"];
+export type RefillContractErrorCode = (typeof REFILL_CONTRACT_ERROR_CODES)[number];
+export declare class RefillContractError extends Error {
+    readonly code: RefillContractErrorCode;
+    constructor(code: RefillContractErrorCode, message: string);
+}
+export declare const REFILL_SCOPE_IDS: readonly ["workspace_id", "target_date", "sender_selectors", "campaign_selectors", "approval_mode", "contract_identity", "installed_identity"];
+export declare const REFILL_GATE_IDS: readonly ["workspace_access", "approval_packet", "source_family", "threshold", "scheduler", "campaign_lifecycle", "send_time", "no_direct_send", "one_primitive", "fresh_reread", "normalized_accounting", "prep_circuit", "terminal_truth"];
+export declare const REFILL_STATE_IDS: readonly ["planning", "awaiting_approval", "executing", "settling", "replanning", "terminal"];
+export declare const REFILL_ACTION_IDS: readonly ["prepare_messages", "approve_messages", "rerun_errored_cells", "start_paused_campaign", "run_scheduler_sweep", "scheduler_first_settle", "wait_for_scheduler", "wait_for_active_work", "wait_for_source_import", "copy_selected_source_rows", "continue_signal_discovery_source", "continue_sales_nav_source", "continue_prospeo_source", "manual_source_replenishment", "refresh_paid_inmail_credits", "lower_paid_inmail_threshold", "switch_to_connection_lane", "create_connection_campaign", "next_campaign", "done"];
+export declare const REFILL_RECEIPT_IDS: readonly ["target_plan_receipt", "preparation_receipt", "scheduler_receipt", "run_receipt"];
+export declare const REFILL_SIDE_EFFECT_CLASS_IDS: readonly ["read_only", "message_preparation", "message_approval", "source_replenishment", "credit_refresh", "campaign_start", "scheduler_placement"];
+export declare const REFILL_FORBIDDEN_ACTION_IDS: readonly ["direct_send", "raw_scheduler_write", "campaign_create", "campaign_archive_delete", "threshold_lowering", "unselected_source_mutation", "unapproved_campaign_start", "sender_config_write"];
+export declare const REFILL_TERMINAL_REASON_IDS: readonly ["projected_full", "concrete_blocker", "deadline_reached", "iteration_limit", "operator_stopped", "capped_by_scheduler", "loaded_awaiting_scheduler", "lanes_exhausted", "not_an_evergreen_workspace", "no_refillable_campaigns"];
+export type RefillScopeId = (typeof REFILL_SCOPE_IDS)[number];
+export type RefillGateId = (typeof REFILL_GATE_IDS)[number];
+export type RefillStateId = (typeof REFILL_STATE_IDS)[number];
+export type RefillActionId = (typeof REFILL_ACTION_IDS)[number];
+export type RefillReceiptId = (typeof REFILL_RECEIPT_IDS)[number];
+export type RefillSideEffectClassId = (typeof REFILL_SIDE_EFFECT_CLASS_IDS)[number];
+export type RefillForbiddenActionId = (typeof REFILL_FORBIDDEN_ACTION_IDS)[number];
+export type RefillTerminalReasonId = (typeof REFILL_TERMINAL_REASON_IDS)[number];
+export type RefillAction = {
+    [Kind in RefillActionId]: {
+        kind: Kind;
+        actionKey: string;
+        sideEffectClass: RefillSideEffectClassId;
+    };
+}[RefillActionId];
+export type RefillReceipt = {
+    [Kind in RefillReceiptId]: {
+        kind: Kind;
+        actionKey: string;
+        recordedAt: string;
+    };
+}[RefillReceiptId];
+export type RefillTerminal = {
+    [Reason in RefillTerminalReasonId]: {
+        kind: "terminal";
+        reason: Reason;
+        evidence: Record<string, unknown>;
+    };
+}[RefillTerminalReasonId];
+export declare function canonicalizeRefillContract(value: unknown): string;
+export declare function computeRefillContractHash(value: unknown): string;
+export declare const REFILL_CONTRACT_HASH: string;
+export declare const refillContract: {
+    readonly contractHash: string;
+    readonly contractVersion: "2.0.0";
+    readonly cacheVersion: "refill-contract-v1";
+    readonly supportedMajor: 2;
+    readonly semantics: {
+        readonly scope: {
+            id: "workspace_id" | "target_date" | "sender_selectors" | "campaign_selectors" | "approval_mode" | "contract_identity" | "installed_identity";
+        }[];
+        readonly gates: {
+            id: "workspace_access" | "approval_packet" | "source_family" | "threshold" | "scheduler" | "campaign_lifecycle" | "send_time" | "no_direct_send" | "one_primitive" | "fresh_reread" | "normalized_accounting" | "prep_circuit" | "terminal_truth";
+        }[];
+        readonly states: {
+            id: "planning" | "awaiting_approval" | "executing" | "settling" | "replanning" | "terminal";
+        }[];
+        readonly actions: {
+            id: "prepare_messages" | "approve_messages" | "rerun_errored_cells" | "start_paused_campaign" | "run_scheduler_sweep" | "scheduler_first_settle" | "wait_for_scheduler" | "wait_for_active_work" | "wait_for_source_import" | "copy_selected_source_rows" | "continue_signal_discovery_source" | "continue_sales_nav_source" | "continue_prospeo_source" | "manual_source_replenishment" | "refresh_paid_inmail_credits" | "lower_paid_inmail_threshold" | "switch_to_connection_lane" | "create_connection_campaign" | "next_campaign" | "done";
+            sideEffectClass: "read_only" | "message_preparation" | "message_approval" | "source_replenishment" | "credit_refresh" | "campaign_start" | "scheduler_placement";
+        }[];
+        readonly receipts: readonly [{
+            readonly id: "target_plan_receipt";
+            readonly requiredFields: readonly ["refillLaneKey", "branchMetrics", "ledger", "targetDate", "actionKey", "targetShapeRevision", "stateRevision"];
+        }, {
+            readonly id: "preparation_receipt";
+            readonly requiredFields: readonly ["dependency", "circuit", "batchCalibration", "cooperativeStop"];
+        }, {
+            readonly id: "scheduler_receipt";
+            readonly requiredFields: readonly ["receiptVersion", "diagnosticsVersion", "status", "trigger", "workspaceId", "runId", "leaseFence", "expectedTargetsHash", "maxPlacements", "readyCellsFound", "cellsConsidered", "cellsScheduled", "cellsSkipped", "cellsDeferred", "campaignScopeSummary", "expectedTargetSummary", "changedCounts", "summary", "nextAction", "errorCount", "error"];
+        }, {
+            readonly id: "run_receipt";
+            readonly requiredFields: readonly ["runId", "fence", "gate", "gateSeq", "events", "doneReason"];
+        }];
+        readonly sideEffectClasses: {
+            id: "read_only" | "message_preparation" | "message_approval" | "source_replenishment" | "credit_refresh" | "campaign_start" | "scheduler_placement";
+        }[];
+        readonly forbiddenActions: {
+            id: "direct_send" | "raw_scheduler_write" | "campaign_create" | "campaign_archive_delete" | "threshold_lowering" | "unselected_source_mutation" | "unapproved_campaign_start" | "sender_config_write";
+        }[];
+        readonly terminalReasons: {
+            id: "projected_full" | "concrete_blocker" | "deadline_reached" | "iteration_limit" | "operator_stopped" | "capped_by_scheduler" | "loaded_awaiting_scheduler" | "lanes_exhausted" | "not_an_evergreen_workspace" | "no_refillable_campaigns";
+            terminalKind: string;
+        }[];
+        readonly transitions: readonly [{
+            readonly from: "planning";
+            readonly to: "awaiting_approval";
+        }, {
+            readonly from: "awaiting_approval";
+            readonly to: "executing";
+        }, {
+            readonly from: "executing";
+            readonly to: "settling";
+        }, {
+            readonly from: "settling";
+            readonly to: "replanning";
+        }, {
+            readonly from: "replanning";
+            readonly to: "executing";
+        }, {
+            readonly from: "replanning";
+            readonly to: "terminal";
+        }];
+    };
+    readonly backendBindings: {
+        readonly planner: {
+            readonly actions: ("prepare_messages" | "approve_messages" | "rerun_errored_cells" | "start_paused_campaign" | "run_scheduler_sweep" | "scheduler_first_settle" | "wait_for_scheduler" | "wait_for_active_work" | "wait_for_source_import" | "copy_selected_source_rows" | "continue_signal_discovery_source" | "continue_sales_nav_source" | "continue_prospeo_source" | "manual_source_replenishment" | "refresh_paid_inmail_credits" | "lower_paid_inmail_threshold" | "switch_to_connection_lane" | "create_connection_campaign" | "next_campaign" | "done")[];
+            readonly receiptFields: readonly ["refillLaneKey", "branchMetrics", "ledger", "targetDate", "actionKey", "targetShapeRevision", "stateRevision"];
+        };
+        readonly preparation: {
+            readonly dependencyClasses: readonly ["active", "transient", "permanent", "changed", "exhausted"];
+            readonly dependencyReasons: readonly ["active_cells", "dependency_timeout", "rate_limited", "provider_unavailable", "authentication_failed", "validation_failed", "schema_invalid", "config_epoch_changed", "source_epoch_changed", "frontier_exhausted", "unknown_dependency"];
+            readonly circuitStates: readonly ["closed", "open", "half_open", "reset"];
+            readonly cooperativeStopReasons: readonly ["target_satisfied_during_prep"];
+            readonly receiptFields: readonly ["dependency", "circuit", "batchCalibration", "cooperativeStop"];
+        };
+        readonly scheduler: {
+            readonly targetOutcomes: readonly ["included", "omitted"];
+            readonly omissionReasons: readonly ["no_ready_cells", "not_scheduler_eligible", "sender_mismatch", "capacity_prefiltered", "outside_target_date", "receipt_error"];
+            readonly runStatuses: readonly ["ran", "window_closed_noop", "failed"];
+            readonly nextActions: readonly ["refresh_paid_inmail_credits_then_rerun", "wait_for_capacity_or_window", "inspect_sender_mismatch", "no_ready_cells_continue_refill_prep", "scheduled_cells", "investigate_deferred_reasons", "investigate_scheduler_failure"];
+            readonly receiptFields: readonly ["receiptVersion", "diagnosticsVersion", "status", "trigger", "workspaceId", "runId", "leaseFence", "expectedTargetsHash", "maxPlacements", "readyCellsFound", "cellsConsidered", "cellsScheduled", "cellsSkipped", "cellsDeferred", "campaignScopeSummary", "expectedTargetSummary", "changedCounts", "summary", "nextAction", "errorCount", "error"];
+        };
+        readonly run: {
+            readonly gates: readonly ["g0_bootstrap", "g1_plan", "g2_execute", "g3_verify", "g4_terminal"];
+            readonly states: readonly ["planning", "awaiting_approval", "executing", "settling", "replanning", "terminal"];
+            readonly resultKinds: readonly ["started", "awaiting_approval", "active_run_in_progress", "resumed", "lease_lost", "scope_drift", "approval_expired", "approval_fingerprint_mismatch"];
+            readonly terminalReasons: readonly ["complete", "capped_by_scheduler", "loaded_awaiting_scheduler", "lanes_exhausted", "blocked", "not_an_evergreen_workspace", "no_refillable_campaigns"];
+            readonly refusals: readonly ["scope_drift", "approval_expired", "approval_fingerprint_mismatch", "legacy_read_only", "expected_target_overflow", "scheduler_receipt_incomplete"];
+            readonly scopeFields: readonly ["workspaceId", "intent", "senderIds", "campaignIds", "tableIds", "actionIds", "approvalMode", "dateSelector", "senderTimezones", "expectedTargetsHash", "maxPlacements", "contract", "installed"];
+            readonly approvalFields: readonly ["scopeHash", "targetShapeRevision", "actionFingerprint", "expectedTargetsHash", "sideEffectEnvelope", "maxPlacements", "approvalExpiresAt", "approvalFingerprint"];
+        };
+    };
+};
+export type RefillContract = typeof refillContract;
+export declare function assertSupportedRefillContractMajor(version: string): void;
+export declare function validateRefillContractAsset(value: unknown): RefillContract;
+export declare function refillContractSemanticProjection(): {
+    contractVersion: "2.0.0";
+    cacheVersion: "refill-contract-v1";
+    contractHash: string;
+    semanticIds: {
+        [k: string]: string[];
+    };
+};
+export declare function validateRefillFlowProjection(value: unknown): void;
+export declare function renderRefillBootstrapGuidance(): string;
+export declare function renderRefillSafetyGuidance(): string;
+export declare function renderRefillTerminalGuidance(): string;
+export declare function assertNeverRefillVariant(value: never): never;