@convertcom/mcp-server 0.0.1-beta.17 → 0.0.1-beta.18

package/build/operator.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { executeNamespacedTool, namespaceToolNameForAction } from './namespaced.js';
 import { JSON_SCHEMA_DRAFT_2020_12 } from './shared.js';
 import { scrubDiagnosticText } from './redaction.js';
+import { failureAttribution, failureFromStructured, inputFailure, safeFailureAttribution, } from './failure-attribution.js';
 import { FEEDBACK_BODY_SCHEMA, FEEDBACK_CONFIRMATION_SCHEMA, FeedbackContractError, feedbackConsentProof, feedbackSubmissionContextOutline, feedbackSubmissionDigest, sanitizeFeedbackBody, validateAndSanitizeFeedback, } from './feedback.js';
 const APPROVAL_RULE_CODES = new Set([
     'experience.activate',
@@ -129,7 +130,7 @@ const READ_ACTIONS = [
     {
         action: 'get_defaults',
         mode: 'read',
-        description: 'Infer and cache project defaults such as preferred goal, audience, location, URL, and traffic split.',
+        description: 'Infer and cache suggested project defaults such as preferred goal, audience, location, URL, and traffic split. Suggestions are not consent to attach or create a resource.',
         path_parameters: ['account_id', 'project_id'],
         accepts_body: true,
     },
@@ -145,14 +146,14 @@ const WRITE_ACTIONS = [
     {
         action: 'create_custom_code_ab_test',
         mode: 'write',
-        description: 'Create a draft custom-code A/B experience and verify the persisted payload. Required body: url plus non-empty js or css. Optional: name, control_name, variation_name, description, objective, primary_goal, goals, audiences, locations, settings. Canonical custom variations may be supplied as variations[].changes[] with at most 100 changes per variation for bounded verification. Payload verification is independent from attached-goal lifecycle health; goal_configuration reports archived or unresolved goals without encouraging a duplicate create. Returns one authoritative experience plus a compact create receipt. Unknown fields are rejected.',
+        description: 'Create a draft custom-code A/B experience and verify the persisted payload. Required body: url plus non-empty js or css. Optional: name, control_name, variation_name, description, objective, primary_goal, goals, audiences, locations, settings. Omitted goals and goals: [] can both trigger Convert goal fallback; resolve user-intended existing goals and primary, send explicit IDs, and inspect the expanded returned experience. A bare URL does not select the UI Experience URL location; attach a user-intended location explicitly. Canonical custom variations may be supplied as variations[].changes[] with at most 100 changes per variation for bounded verification. Payload verification is independent from attached-goal lifecycle health; goal_configuration reports archived or unresolved goals without encouraging a duplicate create. Returns one authoritative experience plus a compact create receipt. Unknown fields are rejected.',
         path_parameters: ['account_id', 'project_id'],
         accepts_body: true,
     },
     {
         action: 'create_split_url_test',
         mode: 'write',
-        description: 'Create a draft split URL experience with an Original no-redirect control and a redirect treatment, allocated 50/50, and verify both arms, baseline, allocation and redirects. Required body: original_pattern (or url) and variation_pattern (variation_url and redirect_url are accepted aliases). Optional: name, variation_name, case_sensitive, description, objective, primary_goal, goals, audiences, locations, settings, split_regex_support. Custom variations require unique names, exactly one explicit is_baseline: true control with no changes, one defaultRedirect per treatment, and positive numeric traffic_distribution per arm totaling 100; at most 100 changes per variation. goal_configuration separately reports archived or unresolved goals. Returns one authoritative experience plus a create receipt. If verified is false, inspect that existing draft; never repeat create or activate it automatically. Unknown fields are rejected.',
+        description: 'Create a draft split URL experience with an Original no-redirect control and a redirect treatment, allocated 50/50, and verify both arms, baseline, allocation and redirects. Required body: original_pattern (or url) and variation_pattern (variation_url and redirect_url are accepted aliases). Optional: name, variation_name, case_sensitive, description, objective, primary_goal, goals, audiences, locations, settings, split_regex_support. Omitted goals and goals: [] can both trigger Convert goal fallback; resolve user-intended existing goals and primary, send explicit IDs, and inspect the expanded returned experience. A bare URL does not select the UI Experience URL location; attach a user-intended location explicitly. Custom variations require unique names, exactly one explicit is_baseline: true control with no changes, one defaultRedirect per treatment, and positive numeric traffic_distribution per arm totaling 100; at most 100 changes per variation. goal_configuration separately reports archived or unresolved goals. Returns one authoritative experience plus a create receipt. If verified is false, inspect that existing draft; never repeat create or activate it automatically. Unknown fields are rejected.',
         path_parameters: ['account_id', 'project_id'],
         accepts_body: true,
     },
@@ -172,6 +173,10 @@ const WRITE_ACTIONS = [
     },
 ];
 const ALL_ACTIONS = [...READ_ACTIONS, ...WRITE_ACTIONS];
+const ALL_ACTION_NAMES = new Set(ALL_ACTIONS.map((action) => action.action));
+export function isRegisteredOperatorAction(action) {
+    return typeof action === 'string' && ALL_ACTION_NAMES.has(action);
+}
 const DEFAULT_RESULTS_PER_PAGE = 50;
 const MAX_OPERATOR_COLLECTION_PAGES = 20;
 const MAX_OPERATOR_COLLECTION_BYTES = 8 * 1024 * 1024;
@@ -254,6 +259,9 @@ export const OPERATOR_OUTPUT_SCHEMA = {
         error: {},
         issues: { type: 'array', items: { type: 'object' } },
         verified: { type: 'boolean' },
+        failure: { type: 'object', description: 'Closed, identifier-free failure category and provenance for a failed operator call.' },
+        partial_failure_count: { type: 'integer', minimum: 1, description: 'Number of failed namespace calls when an operator workflow still returned partial evidence.' },
+        partial_failure: { type: 'object', description: 'Closed, identifier-free dominant failure category and provenance for a partially successful workflow.' },
     },
     additionalProperties: true,
 };
@@ -617,7 +625,7 @@ async function prepareFeedback(args, toolSet, readOnlyImpersonation) {
             approved_payload_digest: digest,
         },
         next_step: submitAvailable
-            ? 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. Explain that context values are intentionally not re-echoed and that the digest binds approval to the complete sanitized payload. Only after explicit approval, call submit_feedback with the unchanged body and set all three confirmation_template booleans to true.'
+            ? 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. Explain that context values are intentionally not re-echoed and that the digest binds approval to the complete sanitized payload. Only after explicit approval, call submit_feedback with the unchanged body and set all three confirmation_template booleans to true. If the host reports no approval while the confirmation matches this template exactly, the host failed to capture approval: re-present the host approval card instead of editing the confirmation.'
             : readOnlyImpersonation
                 ? 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. Staff impersonation is browse-only, so this preparation cannot be submitted or attributed as the customer. Remove as_user and prepare the feedback again as the connected staff member if they explicitly want to submit it.'
                 : 'Show the sanitized summary, context outline, context byte count, payload digest, and review_contract to the user. This read-only MCP profile cannot store feedback; do not claim submission. A write-enabled Convert MCP profile is required after approval.',
@@ -941,15 +949,23 @@ async function experimentPortfolio(args, context) {
 }
 async function experimentVelocity(args, context) {
     await report(context, 'Fetching experiences for velocity report', 1, 3);
-    const experienceCall = await listExperiences(basePath(args), portfolioFilters(args));
+    const [experienceCall, goalCall] = await Promise.all([
+        listExperiences(basePath(args), portfolioFilters(args)),
+        listResource('goals', basePath(args)),
+    ]);
     const experiences = collectionFrom(experienceCall.data);
-    const summaries = summarizeExperiences(experiences);
+    const summaries = summarizeExperiences(experiences, canonicalGoalDefinitions(collectionFrom(goalCall.data)));
+    const goalCoverage = investigationCollectionCoverage(goalCall);
     const launched = summaries.filter((item) => typeof item.start_time === 'number' && item.start_time > 0);
     const completed = summaries.filter((item) => typeof item.end_time === 'number' && item.end_time > 0);
     const coverage = investigationCollectionCoverage(experienceCall);
     const completeCoverage = coverage.status === 'complete';
     return {
-        source_status: { experiences: experienceCall.ok ? 'available' : 'unavailable' },
+        source_status: {
+            experiences: experienceCall.ok ? 'available' : 'unavailable',
+            goals: goalCall.ok ? 'available' : 'unavailable',
+        },
+        goal_authority_coverage: goalCoverage,
         coverage,
         total: experienceCall.ok && completeCoverage ? summaries.length : null,
         created_or_returned: experienceCall.ok ? summaries.length : null,
@@ -974,7 +990,8 @@ async function experimentVelocity(args, context) {
             ...(experienceCall.ok && !completeCoverage
                 ? [`Experience velocity coverage is ${coverage.status}; exact totals and averages are null, while returned_* fields describe only fetched rows.`]
                 : []),
-            ...warningsFromCalls([experienceCall]),
+            ...goalAuthorityWarnings(goalCoverage),
+            ...warningsFromCalls([experienceCall, goalCall]),
         ],
     };
 }
@@ -1474,9 +1491,13 @@ async function investigate(args, context) {
 }
 async function failedTestAnalysis(args, context) {
     await report(context, 'Fetching completed and paused experiences', 1, 3);
-    const experienceCall = await listExperiences(basePath(args), { status: ['completed', 'paused'] });
+    const [experienceCall, goalCall] = await Promise.all([
+        listExperiences(basePath(args), { status: ['completed', 'paused'] }),
+        listResource('goals', basePath(args)),
+    ]);
     const experiences = collectionFrom(experienceCall.data);
-    const summaries = summarizeExperiences(experiences);
+    const summaries = summarizeExperiences(experiences, canonicalGoalDefinitions(collectionFrom(goalCall.data)));
+    const goalCoverage = investigationCollectionCoverage(goalCall);
     const applicable = summaries.filter((item) => item.outcome !== 'not_applicable');
     const losses = applicable.filter((item) => [
         'negative',
@@ -1488,7 +1509,11 @@ async function failedTestAnalysis(args, context) {
     const coverage = investigationCollectionCoverage(experienceCall);
     const completeCoverage = coverage.status === 'complete';
     return {
-        source_status: { experiences: experienceCall.ok ? 'available' : 'unavailable' },
+        source_status: {
+            experiences: experienceCall.ok ? 'available' : 'unavailable',
+            goals: goalCall.ok ? 'available' : 'unavailable',
+        },
+        goal_authority_coverage: goalCoverage,
         coverage,
         returned_reviewed: experienceCall.ok ? summaries.length : null,
         total_reviewed: experienceCall.ok && completeCoverage ? summaries.length : null,
@@ -1509,7 +1534,8 @@ async function failedTestAnalysis(args, context) {
             ...(experienceCall.ok && !completeCoverage
                 ? [`Failed-test analysis coverage is ${coverage.status}; exact totals are null and returned_* fields describe only fetched rows.`]
                 : []),
-            ...warningsFromCalls([experienceCall]),
+            ...goalAuthorityWarnings(goalCoverage),
+            ...warningsFromCalls([experienceCall, goalCall]),
         ],
     };
 }
@@ -1599,20 +1625,27 @@ async function cleanupCandidates(args, context) {
     await report(context, 'Fetching cleanup candidates', 1, 4);
     const path = basePath(args);
     const staleDraftDays = numberFrom(args.body.stale_draft_days ?? args.query.stale_draft_days, 30);
-    const [drafts, allExperiences, goals, audiences, locations, features] = await Promise.all([
+    const [drafts, allExperiences, goals, audiences, locations, features, goalAuthority] = await Promise.all([
         listExperiences(path, { status: ['draft'] }),
         listExperiences(path),
         listResource('goals', path, { usage: 'not_used' }),
         listResource('audiences', path, { usage: 'not_used' }),
         listResource('locations', path, { usage: 'not_used' }),
         listResource('features', path),
+        listResource('goals', path),
     ]);
     const experienceItems = collectionFrom(allExperiences.data);
     const draftItems = collectionFrom(drafts.data);
+    // Shared goals can embed stale or reordered definitions per experience; resolve
+    // every stale-draft summary against the goals authority (draft_qa parity) so a
+    // shared goal reports one consistent type/name/status everywhere. Missing ids
+    // fall back to their embeds, and an unavailable authority is disclosed below.
+    const canonicalGoals = canonicalGoalDefinitions(collectionFrom(goalAuthority.data));
+    const goalAuthorityCoverage = investigationCollectionCoverage(goalAuthority);
     const staleCutoff = Date.now() / 1000 - staleDraftDays * 24 * 60 * 60;
     const staleDrafts = draftItems
         .filter((item) => typeof item.created_at !== 'number' || item.created_at < staleCutoff)
-        .map((experience) => summarizeExperience(experience));
+        .map((experience) => summarizeExperience(experience, canonicalGoals));
     const experienceCoverage = investigationCollectionCoverage(allExperiences);
     const draftCoverage = investigationCollectionCoverage(drafts);
     const completeExperienceCoverage = experienceCoverage.status === 'complete';
@@ -1648,12 +1681,13 @@ async function cleanupCandidates(args, context) {
             sdk_search_patterns: feature.key ? [`${feature.key}`, `isFeatureEnabled(\"${feature.key}\")`, `getFeature(\"${feature.key}\")`] : [],
         };
     });
-    const cleanupWarnings = warningsFromCalls([drafts, allExperiences, goals, audiences, locations, features]);
+    const cleanupWarnings = warningsFromCalls([drafts, allExperiences, goals, audiences, locations, features, goalAuthority]);
     for (const [resource, status] of Object.entries(candidateSourceStatus)) {
         if (status !== 'complete') {
             cleanupWarnings.push(`${resource} cleanup candidates are unavailable because verification status is ${status}; other resource categories remain independently evaluated.`);
         }
     }
+    cleanupWarnings.push(...goalAuthorityWarnings(goalAuthorityCoverage));
     return {
         stale_draft_days: staleDraftDays,
         source_status: {
@@ -1668,6 +1702,7 @@ async function cleanupCandidates(args, context) {
             drafts: draftCoverage,
             experiences: experienceCoverage,
             ...resourceCoverage,
+            goal_authority: goalAuthorityCoverage,
         },
         returned_stale_drafts: drafts.ok ? staleDrafts.length : null,
         total_stale_drafts: drafts.ok && draftCoverage.status === 'complete' ? staleDrafts.length : null,
@@ -2412,6 +2447,7 @@ async function namespaceCall(namespace, action, path, body, query, confirmation)
             error: structured.error ?? text ?? 'Unknown error',
             details: structured,
             text,
+            failure: failureFromStructured(structured, 'namespace'),
         });
     }
     return recordNamespaceCall({
@@ -2437,6 +2473,13 @@ async function safeNamespaceCall(namespace, action, path, body, query) {
             namespace,
             action,
             error: error instanceof Error ? error.name : 'ThrownError',
+            failure: failureAttribution({
+                category: 'unknown',
+                source: 'operator',
+                stage: 'operator_workflow',
+                dispatchState: 'unknown',
+                code: error instanceof Error ? error.name : 'ThrownError',
+            }),
         });
     }
 }
@@ -2460,6 +2503,11 @@ function basePath(args, extra = [], override = {}) {
     }
     return path;
 }
+function goalAuthorityWarnings(coverage) {
+    return coverage.status === 'complete' ? [] : [
+        `Goal type/name/status for unresolved IDs fell back to experience embeds because the goals authority is ${coverage.status}; verify shared goal definitions via goals.get before acting on them.`,
+    ];
+}
 function summarizeExperiences(experiences, canonicalGoals = new Map()) {
     return experiences.map((experience) => summarizeExperience(experience, canonicalGoals));
 }
@@ -3213,11 +3261,25 @@ function stableLifecycleStatus(value) {
         : 'unknown';
 }
 function stableCallErrorClass(call) {
+    if (call.failure?.category === 'input')
+        return 'invalid_input';
+    if (call.failure?.category === 'permission')
+        return call.status === 401 ? 'authentication_failed' : 'permission_denied';
+    if (call.failure?.category === 'not_found')
+        return 'not_found';
+    if (call.failure?.category === 'timeout')
+        return 'upstream_timeout';
+    if (call.failure?.category === 'network')
+        return 'upstream_network_error';
+    if (call.failure?.category === 'cancellation')
+        return 'cancelled';
+    if (call.failure?.category === 'internal')
+        return 'internal_error';
     const status = call.status;
     if (status === 401)
         return 'authentication_failed';
     if (status === 403)
-        return 'permission_denied';
+        return 'upstream_request_failed';
     if (status === 404)
         return 'not_found';
     if (status === 422)
@@ -4018,11 +4080,40 @@ async function report(context, message, progress, total) {
 function finalizeOperatorResult(action, data, calls) {
     const allCallsFailed = calls.length > 0 && calls.every((call) => !call.ok);
     if (!allCallsFailed) {
-        return okResult(action, data);
+        return okResult(action, data, calls);
     }
     const status = dominantFailureStatus(calls);
     const errors = calls.map((call) => `${call.namespace}.${call.action}: ${stableCallErrorClass(call)}`);
-    return errorResult(action, 'AllUpstreamCallsFailed', `All upstream namespace calls failed for operator.${action}.`, { status, data, errors });
+    const partial = operatorFailureSummary(calls);
+    return errorResult(action, 'AllUpstreamCallsFailed', `All upstream namespace calls failed for operator.${action}.`, {
+        status,
+        data,
+        errors,
+        ...(partial ? { failure: partial.failure } : {}),
+    });
+}
+function operatorFailureSummary(calls) {
+    const failures = calls
+        .filter((call) => !call.ok)
+        .map((call) => call.failure ?? failureFromStructured({
+        ...(typeof call.status === 'number' ? { status: call.status } : {}),
+        error: typeof call.error === 'string' ? call.error : 'UnknownFailure',
+    }, 'namespace'));
+    if (failures.length === 0)
+        return null;
+    const priority = new Map([
+        ['permission', 0],
+        ['cancellation', 1],
+        ['timeout', 2],
+        ['network', 3],
+        ['not_found', 4],
+        ['upstream', 5],
+        ['input', 6],
+        ['internal', 7],
+        ['unknown', 8],
+    ]);
+    const failure = failures.slice().sort((left, right) => (priority.get(left.category) ?? 99) - (priority.get(right.category) ?? 99))[0];
+    return { count: failures.length, failure };
 }
 /** The most common HTTP status among failed calls, or 502 when no call reported a numeric status. */
 function dominantFailureStatus(calls) {
@@ -4036,11 +4127,12 @@ function dominantFailureStatus(calls) {
         return 502;
     return [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
 }
-function okResult(action, data) {
+function okResult(action, data, calls = []) {
     const verified = typeof data.verified === 'boolean' ? data.verified : undefined;
     const responseData = verified === undefined ? data : { ...data };
     if (verified !== undefined)
         delete responseData.verified;
+    const partial = operatorFailureSummary(calls);
     const payload = {
         ok: true,
         namespace: 'operator',
@@ -4049,6 +4141,10 @@ function okResult(action, data) {
         status: 200,
         data: responseData,
         ...(verified !== undefined ? { verified } : {}),
+        ...(partial ? {
+            partial_failure_count: partial.count,
+            partial_failure: partial.failure,
+        } : {}),
     };
     return {
         content: [{ type: 'text', text: JSON.stringify(payload) }],
@@ -4059,6 +4155,10 @@ function errorResult(action, code, message, extra = {}) {
     const scrubbedExtra = scrubOperatorErrorValue(extra);
     const safeExtra = isObject(scrubbedExtra) ? scrubbedExtra : {};
     const status = typeof safeExtra.status === 'number' ? safeExtra.status : 400;
+    const existingFailure = safeFailureAttribution(safeExtra.failure);
+    const inferredFailure = code === 'MissingPathParameters'
+        ? inputFailure(code, 'operator', 'required', 'path')
+        : failureFromStructured({ ...safeExtra, error: code }, 'operator');
     const payload = {
         ...safeExtra,
         ok: false,
@@ -4068,6 +4168,7 @@ function errorResult(action, code, message, extra = {}) {
         status,
         error: code,
         message: scrubDiagnosticText(message),
+        failure: existingFailure ?? inferredFailure,
     };
     return {
         isError: true,
@@ -4121,6 +4222,14 @@ function approvalRequiredOperatorErrorResult(action, details) {
         error: 'ApprovalRequired',
         code: 'ApprovalRequired',
         message,
+        failure: failureAttribution({
+            category: 'permission',
+            source: 'operator',
+            stage: 'upstream_response',
+            dispatchState: 'dispatched',
+            code: 'ApprovalRequired',
+            upstreamStatus: 422,
+        }),
         approval_state: approvalState,
         approval_required: {
             rule_code: ruleCode,