@sellable/mcp 0.1.0

package/dist/tools/flow-preflight.js

@@ -0,0 +1,138 @@
+let createCampaignPromptState = null;
+let researchPromptStates = {};
+let latestResearchPromptState = null;
+let senderEnrichmentSnapshot = null;
+let senderResearchCompletionState = null;
+export function markCreateCampaignPromptLoaded() {
+    createCampaignPromptState = {
+        loadedAt: new Date().toISOString(),
+    };
+    return createCampaignPromptState;
+}
+export function markResearchPromptLoaded(mode = "generic", subskillName) {
+    const normalizedSubskillName = subskillName ||
+        (mode === "sender"
+            ? "research-sender"
+            : mode === "prospect"
+                ? "research-prospect"
+                : "research");
+    const state = {
+        loadedAt: new Date().toISOString(),
+        mode,
+        subskillName: normalizedSubskillName,
+    };
+    researchPromptStates[mode] = state;
+    latestResearchPromptState = state;
+    return state;
+}
+export function markSenderEnrichmentObserved(input) {
+    const hasContent = (value) => {
+        if (value == null)
+            return false;
+        if (typeof value === "string")
+            return value.trim().length > 0;
+        if (Array.isArray(value))
+            return value.length > 0;
+        if (typeof value === "object")
+            return Object.keys(value).length > 0;
+        return true;
+    };
+    senderEnrichmentSnapshot = {
+        observedAt: new Date().toISOString(),
+        enrichmentStatus: input.enrichmentStatus,
+        hasCaseStudies: hasContent(input.caseStudies),
+        hasProof: hasContent(input.proof),
+    };
+    // Any fresh enrich_sender call invalidates prior sender research completion.
+    senderResearchCompletionState = null;
+    return senderEnrichmentSnapshot;
+}
+export function markSenderResearchCompleted(input) {
+    const toNonNegativeInteger = (value) => {
+        if (typeof value !== "number" || Number.isNaN(value))
+            return 0;
+        if (!Number.isFinite(value))
+            return 0;
+        return Math.max(0, Math.floor(value));
+    };
+    senderResearchCompletionState = {
+        completedAt: new Date().toISOString(),
+        depth: input?.depth ?? "minimal-verification",
+        proofItemsFound: toNonNegativeInteger(input?.proofItemsFound),
+        caseStudyItemsFound: toNonNegativeInteger(input?.caseStudyItemsFound),
+        credibilitySignalsFound: toNonNegativeInteger(input?.credibilitySignalsFound),
+        notes: input?.notes ?? null,
+    };
+    return {
+        ok: true,
+        ...senderResearchCompletionState,
+    };
+}
+export function assertCreateCampaignPromptLoaded() {
+    if (createCampaignPromptState) {
+        return {
+            ok: true,
+            loadedAt: createCampaignPromptState.loadedAt,
+        };
+    }
+    throw new Error('FLOW_PRECONDITION: create_campaign requires prompt preload. Call get_subskill_prompt({ subskillName: "create-campaign" }) and follow that workflow before create_campaign.');
+}
+export function assertResearchPromptLoaded(mode = "any") {
+    const researchPromptState = mode === "any" ? latestResearchPromptState : researchPromptStates[mode];
+    if (researchPromptState) {
+        return {
+            ok: true,
+            loadedAt: researchPromptState.loadedAt,
+            mode: researchPromptState.mode,
+            subskillName: researchPromptState.subskillName,
+        };
+    }
+    if (mode === "sender") {
+        throw new Error('FLOW_PRECONDITION: net-new create_campaign requires sender research preload. Call get_subskill_prompt({ subskillName: "research-sender" }) and run sender research before create_campaign.');
+    }
+    throw new Error("FLOW_PRECONDITION: research preload missing. Call get_subskill_prompt with the matching research wrapper (research-sender or research-prospect), then run research before continuing.");
+}
+export function assertNetNewCreateCampaignResearchReady() {
+    if (!senderEnrichmentSnapshot) {
+        throw new Error("FLOW_PRECONDITION: net-new create_campaign requires sender enrichment context. Call enrich_sender first.");
+    }
+    const enrichmentLooksComplete = senderEnrichmentSnapshot.enrichmentStatus === "complete" &&
+        senderEnrichmentSnapshot.hasCaseStudies &&
+        senderEnrichmentSnapshot.hasProof;
+    const senderResearchPromptState = researchPromptStates.sender;
+    if (!senderResearchPromptState) {
+        throw new Error('FLOW_PRECONDITION: net-new create_campaign requires sender research after enrich_sender. Call get_subskill_prompt({ subskillName: "research-sender" }) and run sender research before create_campaign.');
+    }
+    if (!senderResearchCompletionState) {
+        throw new Error("FLOW_PRECONDITION: completed sender research is required before create_campaign. After running research-sender, call complete_sender_research({ depth, proofItemsFound, caseStudyItemsFound, credibilitySignalsFound, notes? }).");
+    }
+    if (new Date(senderResearchCompletionState.completedAt).getTime() <
+        new Date(senderEnrichmentSnapshot.observedAt).getTime()) {
+        throw new Error("FLOW_PRECONDITION: sender research completion is stale for the latest enrichment. Rerun research-sender after enrich_sender, then call complete_sender_research before create_campaign.");
+    }
+    return {
+        ok: true,
+        enrichmentStatus: senderEnrichmentSnapshot.enrichmentStatus,
+        hasCaseStudies: senderEnrichmentSnapshot.hasCaseStudies,
+        hasProof: senderEnrichmentSnapshot.hasProof,
+        enrichmentLooksComplete,
+        usedResearchPrompt: Boolean(senderResearchPromptState),
+        researchPromptMode: senderResearchPromptState?.mode ?? null,
+        researchPromptSubskillName: senderResearchPromptState?.subskillName ?? null,
+        researchCompletion: {
+            depth: senderResearchCompletionState.depth,
+            proofItemsFound: senderResearchCompletionState.proofItemsFound,
+            caseStudyItemsFound: senderResearchCompletionState.caseStudyItemsFound,
+            credibilitySignalsFound: senderResearchCompletionState.credibilitySignalsFound,
+            completedAt: senderResearchCompletionState.completedAt,
+        },
+        needsResearch: true,
+    };
+}
+export function resetFlowPreflightState() {
+    createCampaignPromptState = null;
+    researchPromptStates = {};
+    latestResearchPromptState = null;
+    senderEnrichmentSnapshot = null;
+    senderResearchCompletionState = null;
+}

package/dist/tools/framework.d.ts

@@ -0,0 +1,44 @@
+type GetCampaignFrameworkInput = {
+    flowVersion?: "v1" | "v2";
+    includePlugins?: boolean;
+};
+type ProviderRegistryEntry = {
+    id: string;
+    label: string;
+    configPath: string;
+};
+type ProviderRegistry = {
+    version: string;
+    defaultProviderOrder: string[];
+    providers: ProviderRegistryEntry[];
+};
+export declare const frameworkToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            flowVersion: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            includePlugins: {
+                type: string;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+}[];
+export declare function getCampaignFramework(input: GetCampaignFrameworkInput): {
+    flowVersion: "v1" | "v2";
+    policy: string;
+    flow: Record<string, unknown>;
+    providerRegistry: ProviderRegistry;
+    providers: Record<string, unknown>;
+    plugins: unknown[];
+    overrides: Record<string, unknown>;
+    warnings: string[];
+};
+export {};

package/dist/tools/framework.js

@@ -0,0 +1,153 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, isAbsolute, join, resolve } from "path";
+import { resolveWorkspaceRoot } from "../utils/workspace-root.js";
+const entryPath = process.argv[1] ? resolve(process.argv[1]) : process.cwd();
+const entryDir = dirname(entryPath);
+const workspaceRoot = resolveWorkspaceRoot(entryDir);
+const frameworkRoot = join(workspaceRoot, "mcp/sellable/skills/create-campaign");
+const frameworkV2Root = join(workspaceRoot, "mcp/sellable/skills/create-campaign-v2");
+function getFrameworkRoot(flowVersion) {
+    return flowVersion === "v2" ? frameworkV2Root : frameworkRoot;
+}
+function resolveFromRoot(filePath) {
+    if (isAbsolute(filePath))
+        return filePath;
+    return resolve(workspaceRoot, filePath);
+}
+function readJson(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+}
+function loadProviderRegistry() {
+    const registryPath = join(frameworkRoot, "core/providers/registry.json");
+    if (!existsSync(registryPath)) {
+        throw new Error(`Provider registry not found at ${registryPath}`);
+    }
+    return readJson(registryPath);
+}
+function loadProviders(registry) {
+    const providers = {};
+    const warnings = [];
+    for (const entry of registry.providers) {
+        try {
+            const configPath = resolveFromRoot(entry.configPath);
+            providers[entry.id] = readJson(configPath);
+        }
+        catch (error) {
+            warnings.push(`Failed to load provider config for ${entry.id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { providers, warnings };
+}
+function loadPluginRegistry() {
+    const registryPath = join(frameworkRoot, "context/registry.json");
+    if (!existsSync(registryPath))
+        return null;
+    return readJson(registryPath);
+}
+function mergeOverrides(entries) {
+    const merged = {};
+    for (const entry of entries) {
+        if (!entry.overrides)
+            continue;
+        Object.assign(merged, entry.overrides);
+    }
+    return merged;
+}
+function loadPlugins(registry) {
+    if (!registry) {
+        return {
+            plugins: [],
+            overrides: {},
+            warnings: ["Plugin registry not found; continuing without plugins."],
+        };
+    }
+    const enabledEntries = registry.plugins.filter((p) => p.enabled !== false);
+    const warnings = [];
+    const plugins = enabledEntries.map((entry) => {
+        const fullPath = resolveFromRoot(entry.path);
+        if (!existsSync(fullPath)) {
+            warnings.push(`Plugin file missing for ${entry.id}: ${fullPath}`);
+            return {
+                id: entry.id,
+                path: entry.path,
+                description: entry.description || "",
+                content: "",
+                overrides: entry.overrides || {},
+                missing: true,
+            };
+        }
+        const content = readFileSync(fullPath, "utf-8");
+        return {
+            id: entry.id,
+            path: entry.path,
+            description: entry.description || "",
+            content,
+            overrides: entry.overrides || {},
+            missing: false,
+        };
+    });
+    const overrides = mergeOverrides(enabledEntries);
+    return { plugins, overrides, warnings };
+}
+export const frameworkToolDefinitions = [
+    {
+        name: "get_campaign_framework",
+        description: "Load the versioned create-campaign framework (policy, flow, providers, plugins, overrides). Call this at the start of create-campaign.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                flowVersion: {
+                    type: "string",
+                    enum: ["v1", "v2"],
+                    description: "Framework flow version to load (default: v1)",
+                },
+                includePlugins: {
+                    type: "boolean",
+                    description: "Whether to include plugin context and overrides (default: true)",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+export function getCampaignFramework(input) {
+    const flowVersion = input.flowVersion || "v1";
+    const includePlugins = input.includePlugins !== false;
+    const selectedFrameworkRoot = getFrameworkRoot(flowVersion);
+    const versionedPolicyPath = join(selectedFrameworkRoot, "core/policy.md");
+    const policyPath = existsSync(versionedPolicyPath)
+        ? versionedPolicyPath
+        : join(frameworkRoot, "core/policy.md");
+    const flowPath = join(selectedFrameworkRoot, `core/flow.${flowVersion}.json`);
+    if (!existsSync(policyPath)) {
+        throw new Error(`Policy file not found at ${policyPath}`);
+    }
+    if (!existsSync(flowPath)) {
+        throw new Error(`Flow file not found at ${flowPath}`);
+    }
+    const policy = readFileSync(policyPath, "utf-8");
+    const flow = readJson(flowPath);
+    const providerRegistry = loadProviderRegistry();
+    const { providers, warnings: providerWarnings } = loadProviders(providerRegistry);
+    let plugins = [];
+    let overrides = {};
+    let pluginWarnings = [];
+    if (includePlugins) {
+        const pluginRegistry = loadPluginRegistry();
+        const pluginResult = loadPlugins(pluginRegistry);
+        plugins = pluginResult.plugins;
+        overrides = pluginResult.overrides;
+        pluginWarnings = pluginResult.warnings;
+    }
+    return {
+        flowVersion,
+        policy,
+        flow,
+        providerRegistry,
+        providers,
+        plugins,
+        overrides,
+        warnings: [...providerWarnings, ...pluginWarnings],
+    };
+}

package/dist/tools/interaction-mode.d.ts

@@ -0,0 +1,27 @@
+export type InteractionMode = "step-by-step" | "autonomous" | "ask-when-needed";
+export type ApprovalAction = "provider-preflight" | "provider-search" | "import-leads" | "confirm-lead-list";
+export declare function setCampaignInteractionMode(input: {
+    campaignId: string;
+    interactionMode: string;
+}): {
+    readonly campaignId: string;
+    readonly interactionMode: InteractionMode;
+};
+export declare function resolveCampaignInteractionMode(input: {
+    campaignId?: string | null;
+    persistedMode?: unknown;
+}): InteractionMode;
+export declare function assertInteractionApproval(input: {
+    campaignId?: string | null;
+    persistedMode?: unknown;
+    action: ApprovalAction;
+    confirmed?: boolean;
+}): {
+    readonly ok: true;
+    readonly campaignId: string | null;
+    readonly interactionMode: InteractionMode;
+    readonly action: ApprovalAction;
+    readonly needsApproval: boolean;
+    readonly confirmed: boolean;
+};
+export declare function resetInteractionModeState(): void;

package/dist/tools/interaction-mode.js

@@ -0,0 +1,102 @@
+const campaignInteractionMode = new Map();
+function normalizeInteractionMode(input) {
+    if (typeof input !== "string")
+        return null;
+    const normalized = input
+        .trim()
+        .toLowerCase()
+        .replace(/_/g, "-")
+        .replace(/\s+/g, " ");
+    if (normalized === "step-by-step" ||
+        normalized === "step by step" ||
+        normalized === "continue step by step") {
+        return "step-by-step";
+    }
+    if (normalized === "autonomous" ||
+        normalized === "use best judgment" ||
+        normalized === "best judgment" ||
+        normalized === "auto") {
+        return "autonomous";
+    }
+    if (normalized === "ask-when-needed" ||
+        normalized === "ask when needed" ||
+        normalized === "ask only when needed") {
+        return "ask-when-needed";
+    }
+    return null;
+}
+function requiresApproval(interactionMode, action) {
+    if (interactionMode === "step-by-step") {
+        // Provider selection approval should be enough to proceed through
+        // provider preflight + first search without a second "yes".
+        return action === "import-leads" || action === "confirm-lead-list";
+    }
+    if (interactionMode === "ask-when-needed") {
+        return action === "import-leads" || action === "confirm-lead-list";
+    }
+    // autonomous
+    return false;
+}
+export function setCampaignInteractionMode(input) {
+    const campaignId = input.campaignId?.trim();
+    if (!campaignId) {
+        throw new Error("interactionMode update requires campaignId");
+    }
+    const normalized = normalizeInteractionMode(input.interactionMode);
+    if (!normalized) {
+        throw new Error(`Invalid interactionMode: ${input.interactionMode}. Valid values: step-by-step, autonomous, ask-when-needed.`);
+    }
+    campaignInteractionMode.set(campaignId, normalized);
+    return {
+        campaignId,
+        interactionMode: normalized,
+    };
+}
+export function resolveCampaignInteractionMode(input) {
+    const persisted = normalizeInteractionMode(input.persistedMode);
+    const campaignId = input.campaignId?.trim();
+    if (campaignId && persisted) {
+        campaignInteractionMode.set(campaignId, persisted);
+        return persisted;
+    }
+    if (campaignId) {
+        const cached = campaignInteractionMode.get(campaignId);
+        if (cached)
+            return cached;
+    }
+    return "ask-when-needed";
+}
+export function assertInteractionApproval(input) {
+    const interactionMode = resolveCampaignInteractionMode({
+        campaignId: input.campaignId,
+        persistedMode: input.persistedMode,
+    });
+    const needsApproval = requiresApproval(interactionMode, input.action);
+    if (needsApproval && input.confirmed !== true) {
+        const blockingMessage = `Action "${input.action}" requires confirmation in ${interactionMode} mode.`;
+        const diagnostics = {
+            code: "APPROVAL_REQUIRED",
+            safeToProceed: false,
+            campaignId: input.campaignId ?? null,
+            interactionMode,
+            action: input.action,
+            blockingErrors: [blockingMessage],
+            nextStep: "Ask the user for confirmation, then retry the same tool call with confirmed: true.",
+        };
+        const error = new Error(`APPROVAL_REQUIRED: ${blockingMessage} Next step: ${diagnostics.nextStep}`);
+        error.diagnostics =
+            diagnostics;
+        throw error;
+    }
+    return {
+        ok: true,
+        campaignId: input.campaignId ?? null,
+        interactionMode,
+        action: input.action,
+        needsApproval,
+        confirmed: input.confirmed === true,
+    };
+}
+export function resetInteractionModeState() {
+    campaignInteractionMode.clear();
+}