@copado/agentia-cli 1.2.0 → 1.4.0

package/dist/lib/mcp/tools.js

@@ -2,9 +2,9 @@
 import { z } from 'zod';
 import { buildMetadataCompareFileRequests } from '../../commands/cicd/metadata/content/compare.js';
 import { buildMetadataContentRequest } from '../../commands/cicd/metadata/content/get.js';
+import { buildDependencyRequest, enrichDependencyResult, } from '../../commands/cicd/metadata/dependency/list.js';
 import { buildMetadataCompareRequest } from '../../commands/cicd/metadata/index/compare.js';
 import { buildMetadataIndexRequest } from '../../commands/cicd/metadata/list.js';
-import { AI_METADATA_ACTIONS, buildAiMetadataToolRequest, callAiMetadataTool, } from '../metadata-explore.js';
 import { assertRequired } from '../assert.js';
 import { applyAuthSet, getAiAuthStatus, getCicdAuthStatus, getCrtAuthStatus } from '../auth-config.js';
 import { CicdGateway } from '../cicd-gateway.js';
@@ -17,12 +17,14 @@ import { createEnvironmentCredential, listCredentials, resolveEnvironmentOrgType
 import { buildCreatePayload, buildMutationPayload, ENVIRONMENT_STRING_VALIDATION_KEYS, validateNonEmptyStringFields, } from '../environment-flags.js';
 import { fetchEnvironment, fetchEnvironments } from '../environment-get.js';
 import { DEFAULT_ENVIRONMENT_PLATFORM, DEFAULT_ENVIRONMENT_TYPE, ENVIRONMENT_TYPES, environmentEndpoint, } from '../environment-types.js';
+import { fetchFunctions } from '../function-list.js';
 import { executeLocalFunctionRun } from '../function-local-run.js';
-import { FUNCTION_LIST_TYPES, FUNCTION_RUNTIMES, functionEndpoint, functionResultEndpoint, functionResultLogEndpoint, functionRunEndpoint, functionsEndpoint, normalizeFunction, normalizeFunctionResultStatus, normalizeFunctionRunResult, normalizeFunctionsListPage, normalizeFunctionUpsertPayload, } from '../function-types.js';
-import { fetchJob, fetchJobs } from '../job-get.js';
+import { FUNCTION_LIST_TYPES, FUNCTION_RUNTIMES, functionEndpoint, functionResultEndpoint, functionResultLogEndpoint, functionRunEndpoint, functionsEndpoint, normalizeFunction, normalizeFunctionResultStatus, normalizeFunctionRunResult, normalizeFunctionUpsertPayload, } from '../function-types.js';
+import { fetchJob, fetchJobs, resolveJobResultFileId } from '../job-get.js';
 import { jobEndpoint, jobKillEndpoint, jobPauseEndpoint, jobResultFileContentEndpoint, jobResultFilesEndpoint, jobResultLogEndpoint, jobResumeEndpoint, jobRunEndpoint, normalizeJob, normalizeJobOperation, normalizeJobResultFileContent, normalizeJobResultFiles, resolveJobStepForLog, } from '../job-types.js';
 import { listPaginationZodFields, mcpPaginatedListPayload } from '../list-pagination.js';
 import { COMPARISON_MODES, CONTENT_SOURCES, contentResultToCompareSide, createUnifiedDiff, INDEX_SOURCES, MODULE_TYPES, ORDER_DIRECTIONS, PLATFORM_EXPERIENCES, RETRIEVE_MODES, sourceSideLabel, } from '../metadata-common.js';
+import { AI_METADATA_ACTIONS, buildAiMetadataToolRequest, callAiMetadataTool, } from '../metadata-explore.js';
 import { buildRefreshDeletedRequest, buildRefreshIndexRequest, refreshStatusEndpoint, resolveRefreshSourceFromEnv, } from '../metadata-refresh.js';
 import { NAVIGATION_RESOURCE_TYPES, resolveNavigationTarget } from '../navigation.js';
 import { configureNotification, NOTIFICATION_DESTINATION_TYPES, NOTIFICATION_EVENTS, NOTIFICATION_SUBSCRIPTIONS, withNotificationConfigureErrorTranslation, } from '../notifications-configure.js';
@@ -41,14 +43,18 @@ import { normalizeProject, projectEndpoint, projectsListEndpoint, } from '../pro
 import { buildPromotionConflictResolutionRequest, normalizePromotionConflicts, PROMOTION_CONFLICT_MODES, promotionConflictContentEndpoint, promotionConflictResolveEndpoint, promotionConflictsEndpoint, promotionConflictUndoEndpoint, withPromotionConflictErrorTranslation, } from '../promotion-conflicts.js';
 import { fetchPromotion, fetchPromotions } from '../promotion-get.js';
 import { buildPromotionManualTaskUpdatePayload, PROMOTION_MANUAL_TASK_STATUSES, promotionManualTaskEndpoint, } from '../promotion-job-steps.js';
+import { fetchPromotionQueue, removePromotionQueueItems } from '../promotion-queue.js';
 import { performPromotionResume, performPromotionRun, PROMOTION_OPERATIONS, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, } from '../promotion-run.js';
+import { fetchPromotionStatus } from '../promotion-status.js';
 import { REPOSITORY_STRING_VALIDATION_KEYS, validateNonEmptyStringFields as validateRepositoryNonEmptyStringFields, } from '../repository-flags.js';
-import { normalizeRepositoriesListPage, normalizeRepository, normalizeRepositoryValidateResult, repositoriesEndpoint, REPOSITORY_PROVIDERS, REPOSITORY_SOURCE_FORMATS, repositoryEndpoint, repositoryHttpsAuthEndpoint, repositoryResetEndpoint, repositorySshAuthEndpoint, repositoryValidateEndpoint, } from '../repository-types.js';
+import { fetchRepositories } from '../repository-list.js';
+import { normalizeRepository, normalizeRepositoryValidateResult, repositoriesEndpoint, REPOSITORY_PROVIDERS, REPOSITORY_SOURCE_FORMATS, repositoryEndpoint, repositoryHttpsAuthEndpoint, repositoryResetEndpoint, repositorySshAuthEndpoint, repositoryValidateEndpoint, } from '../repository-types.js';
 import { buildStageMutationPayload, validateStagePayload } from '../stage-flags.js';
 import { fetchStages } from '../stage-list.js';
 import { normalizePipelineStageConnection, normalizeStage, pipelineStageConnectionEndpoint, pipelineStageConnectionsEndpoint, STAGE_META_STAGE_SUGGESTIONS, stageEndpoint, stagesEndpoint, } from '../stage-types.js';
 import { buildTemplateDefaultsQuery } from '../template-flags.js';
-import { normalizeTemplate, normalizeTemplatesListPage, normalizeTemplateUpsertPayload, TEMPLATE_LIST_TYPES, templateDefaultsEndpoint, templateEndpoint, templatesEndpoint, } from '../template-types.js';
+import { fetchTemplates } from '../template-list.js';
+import { normalizeTemplate, normalizeTemplateUpsertPayload, TEMPLATE_LIST_TYPES, templateDefaultsEndpoint, templateEndpoint, } from '../template-types.js';
 import { getUserContext } from '../user-context.js';
 import { fetchUser } from '../user-get.js';
 import { DEFAULT_USER_ID } from '../user-types.js';
@@ -81,6 +87,9 @@ async function promotionList(args = {}) {
 async function promotionGet(args) {
     return { promotion: await fetchPromotion(assertRequired(args.id, 'id')) };
 }
+async function promotionStatus(args) {
+    return { status: await fetchPromotionStatus(assertRequired(args.id, 'id')) };
+}
 async function promotionRun(args) {
     const waitTimeout = args.waitTimeout ?? PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS;
     if (!Number.isInteger(waitTimeout) || waitTimeout <= 0) {
@@ -287,6 +296,12 @@ async function jobPause(args) {
     });
     return { result: normalizeJobOperation(result) };
 }
+async function promotionQueueList(args) {
+    return { queue: await fetchPromotionQueue(assertRequired(args.promotion, 'promotion')) };
+}
+async function promotionQueueRemove(args) {
+    return { queue: await removePromotionQueueItems(assertRequired(args.promotion, 'promotion'), args.itemIds) };
+}
 async function pipelineList(args = {}) {
     return mcpPaginatedListPayload('pipelines', await fetchPipelines(args));
 }
@@ -504,11 +519,7 @@ async function projectList(args = {}) {
     return mcpPaginatedListPayload('projects', await fetchProjects(args));
 }
 async function repositoryList(args = {}) {
-    const response = await CicdGateway.call({
-        endpoint: repositoriesEndpoint(args),
-        method: 'GET',
-    });
-    return mcpPaginatedListPayload('repositories', normalizeRepositoriesListPage(response));
+    return mcpPaginatedListPayload('repositories', await fetchRepositories(args));
 }
 async function repositoryGet(args) {
     const response = await CicdGateway.call({
@@ -597,11 +608,7 @@ async function repositoryValidate(args) {
     return { validation: normalizeRepositoryValidateResult(response) };
 }
 async function functionList(args = {}) {
-    const response = await CicdGateway.call({
-        endpoint: functionsEndpoint({ ...args, type: args.type ?? 'custom' }),
-        method: 'GET',
-    });
-    return mcpPaginatedListPayload('functions', normalizeFunctionsListPage(response));
+    return mcpPaginatedListPayload('functions', await fetchFunctions({ ...args, type: args.type ?? 'custom' }));
 }
 async function functionGet(args) {
     const response = await CicdGateway.call({
@@ -647,11 +654,7 @@ async function functionDelete(args) {
     return { apiName };
 }
 async function templateList(args = {}) {
-    const response = await CicdGateway.call({
-        endpoint: templatesEndpoint({ ...args, type: args.type ?? 'custom' }),
-        method: 'GET',
-    });
-    return mcpPaginatedListPayload('templates', normalizeTemplatesListPage(response));
+    return mcpPaginatedListPayload('templates', await fetchTemplates({ ...args, type: args.type ?? 'custom' }));
 }
 async function templateGet(args) {
     const response = await CicdGateway.call({
@@ -999,44 +1002,47 @@ async function metadataExplore(args) {
         output,
     };
 }
-async function metadataDependencyList(args) {
-    const selection = {
-        name: assertRequired(args.metadataName, 'metadataName'),
-        type: assertRequired(args.metadataType, 'metadataType'),
-    };
-    if (args.metadataCategory) {
-        selection.category = args.metadataCategory;
-    }
-    const body = {
-        compareOptions: {
-            sourceCredentialId: assertRequired(args.sourceCredentialId, 'sourceCredentialId'),
-            sourceOrgId: assertRequired(args.sourceOrgId, 'sourceOrgId'),
-        },
-        metadataSelections: [selection],
-        pipelineId: assertRequired(args.pipelineId, 'pipelineId'),
-    };
-    if (args.targetOrgId) {
-        body.compareOptions.targetOrgId = args.targetOrgId;
-    }
-    if (args.retrieveMode) {
-        body.compareOptions.retrieveMode = args.retrieveMode;
-    }
-    if (args.moduleType) {
-        body.moduleType = args.moduleType;
+function normalizeDependencyPathArg(path) {
+    if (path === undefined) {
+        return undefined;
     }
-    if (args.resultId) {
-        body.resultId = args.resultId;
+    const paths = (Array.isArray(path) ? path : [path]).map((entry) => entry.trim()).filter(Boolean);
+    return paths.length > 0 ? paths : undefined;
+}
+async function metadataDependencyList(args) {
+    const paths = normalizeDependencyPathArg(args.path);
+    if (paths && (args.metadataName || args.metadataType)) {
+        throw new Error('Use either path or metadataName/metadataType, not both.');
     }
-    const platformExperience = args.platformExperience ?? 'salesforce';
-    const result = await CicdGateway.call({
+    const { body, localPathsBySelection, platformExperience } = await buildDependencyRequest({
+        'base-ref': 'origin/main',
+        'from-changes': false,
+        'metadata-category': args.metadataCategory,
+        'metadata-name': args.metadataName,
+        'metadata-type': args.metadataType,
+        'module-type': args.moduleType,
+        path: paths,
+        'pipeline-id': args.pipelineId,
+        'platform-experience': args.platformExperience,
+        'result-id': args.resultId,
+        'retrieve-mode': args.retrieveMode,
+        'source-credential-id': args.sourceCredentialId,
+        'source-org-id': args.sourceOrgId,
+        stdin: false,
+        'target-org-id': args.targetOrgId,
+    });
+    const gatewayResult = await CicdGateway.call({
         body,
         endpoint: '/release/metadata/dependencies',
         headers: {
             'Content-Type': 'application/json',
-            'platform-experience': platformExperience,
+            ...(platformExperience === undefined ? {} : { 'platform-experience': platformExperience }),
         },
         method: 'POST',
     });
+    const result = localPathsBySelection
+        ? await enrichDependencyResult(gatewayResult, localPathsBySelection, args.moduleType)
+        : gatewayResult;
     return { result };
 }
 function authCredentialResult(type) {
@@ -1108,8 +1114,9 @@ async function jobResultFileList(args) {
 }
 async function jobResultFileGet(args) {
     const resultId = assertRequired(args.resultId, 'resultId');
+    const fileId = await resolveJobResultFileId(resultId, assertRequired(args.fileId, 'fileId'));
     const response = await CicdGateway.call({
-        endpoint: jobResultFileContentEndpoint(resultId, assertRequired(args.fileId, 'fileId')),
+        endpoint: jobResultFileContentEndpoint(resultId, fileId),
         method: 'GET',
     });
     return { file: { ...normalizeJobResultFileContent(response), resultId } };
@@ -1353,6 +1360,8 @@ export const agentiaMcpToolHandlers = wrapMcpToolHandlers({
     promotionGet,
     promotionJobStepUpdate,
     promotionList,
+    promotionQueueList,
+    promotionQueueRemove,
     promotionRun,
     repositoryCreate,
     repositoryDelete,
@@ -1546,6 +1555,13 @@ export function registerAgentiaMcpTools(server) {
         },
         title: 'Agentia Promotion Get',
     }, (args) => safelyHandleTool(() => promotionGet(args)));
+    server.registerTool('agentia_promotion_status', {
+        description: 'Get actionable Copado promotion status: user stories, current job step, queue summary, and Manual Task or queue action-needed. Prefer this when the user asks whether a promotion is blocked or what is running.',
+        inputSchema: {
+            id: z.string().describe('Copado promotion Id.'),
+        },
+        title: 'Agentia Promotion Status',
+    }, (args) => safelyHandleTool(() => promotionStatus(args)));
     server.registerTool('agentia_promotion_run', {
         description: 'Preflight, start, and optionally wait for a Copado promotion. Can also resume an existing execution without starting a duplicate run.',
         inputSchema: {
@@ -1643,6 +1659,19 @@ export function registerAgentiaMcpTools(server) {
         },
         title: 'Agentia Job Pause',
     }, (args) => safelyHandleTool(() => jobPause(args)));
+    server.registerTool('agentia_promotion_queue_list', {
+        description: 'List the promotion queue for a Copado promotion via the CICD gateway.',
+        inputSchema: { promotion: z.string().describe('Copado promotion ID or name.') },
+        title: 'Agentia Promotion Queue List',
+    }, (args) => safelyHandleTool(() => promotionQueueList(args)));
+    server.registerTool('agentia_promotion_queue_remove', {
+        description: 'Remove items from a Copado promotion promotion queue via the CICD gateway (requires the Manage Queue permission).',
+        inputSchema: {
+            itemIds: z.array(z.string()).min(1).describe('Queue item IDs to remove (from agentia_promotion_queue_list).'),
+            promotion: z.string().describe('Copado promotion ID or name.'),
+        },
+        title: 'Agentia Promotion Queue Remove',
+    }, (args) => safelyHandleTool(() => promotionQueueRemove(args)));
     server.registerTool('agentia_pipeline_list', {
         description: 'List Copado pipelines via the CICD gateway.',
         inputSchema: {
@@ -1956,19 +1985,44 @@ export function registerAgentiaMcpTools(server) {
         title: 'Agentia Metadata Content Compare',
     }, (args) => safelyHandleTool(() => metadataContentCompare(args)));
     server.registerTool('agentia_metadata_dependency_list', {
-        description: 'Retrieve metadata dependencies.',
+        description: 'Retrieve metadata dependencies. Provide either path (one or more local Salesforce source files) or both metadataName and metadataType. pipelineId, sourceCredentialId, sourceOrgId, and platformExperience default from the active work item or project defaults when omitted; targetOrgId is never inferred.',
         inputSchema: {
             metadataCategory: z.string().optional().describe('Optional metadata category.'),
-            metadataName: z.string().describe('Metadata API name.'),
-            metadataType: z.string().describe('Metadata type, for example ApexClass.'),
+            metadataName: z
+                .string()
+                .optional()
+                .describe('Metadata API name. Required with metadataType when path is omitted.'),
+            metadataType: z
+                .string()
+                .optional()
+                .describe('Metadata type, for example ApexClass. Required with metadataName when path is omitted.'),
             moduleType: z.enum(MODULE_TYPES).optional().describe('Optional addon module type.'),
-            pipelineId: z.string().describe('Pipeline Id.'),
-            platformExperience: z.enum(PLATFORM_EXPERIENCES).optional().describe('Platform experience header.'),
+            path: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe('Local Salesforce source file path(s) resolved into metadata selections. Mutually exclusive with metadataName/metadataType.'),
+            pipelineId: z
+                .string()
+                .optional()
+                .describe('Pipeline Id. Defaults to the active work item pipelineId or the project default pipeline.'),
+            platformExperience: z
+                .enum(PLATFORM_EXPERIENCES)
+                .optional()
+                .describe('Platform experience header. Defaults to the active work item platform, then sfdx.'),
             resultId: z.string().optional().describe('Optional result Id from a prior metadata operation.'),
             retrieveMode: z.enum(RETRIEVE_MODES).optional().describe('Dependency retrieve mode.'),
-            sourceCredentialId: z.string().describe('Source org credential Id.'),
-            sourceOrgId: z.string().describe('Source org Id.'),
-            targetOrgId: z.string().optional().describe('Optional target org Id.'),
+            sourceCredentialId: z
+                .string()
+                .optional()
+                .describe('Source org credential Id. Defaults to the active work item source credential or the project default credential.'),
+            sourceOrgId: z
+                .string()
+                .optional()
+                .describe('Source org Id. Defaults to the active work item sourceOrgId or orgId from the resolved credential/environment.'),
+            targetOrgId: z
+                .string()
+                .optional()
+                .describe('Optional target org Id. Not inferred from work item or project defaults.'),
         },
         title: 'Agentia Metadata Dependency List',
     }, (args) => safelyHandleTool(() => metadataDependencyList(args)));
@@ -2028,7 +2082,9 @@ export function registerAgentiaMcpTools(server) {
     server.registerTool('agentia_job_result_file_get', {
         description: 'Get a File linked to a Copado job Result.',
         inputSchema: {
-            fileId: z.string().describe('File ID returned by result-file list.'),
+            fileId: z
+                .string()
+                .describe('fileId returned by result-file list (068...); contentDocumentId (069...) is resolved automatically'),
             resultId: z.string().describe('Copado Result ID.'),
         },
         title: 'Agentia Job Result File Get',

package/dist/lib/mcp/work-tools.js

@@ -9,20 +9,22 @@ import { listPaginationZodFields, mcpPaginatedListPayload } from '../list-pagina
 import { LocalQualityGatesError, parseQualityGatesEnvAssignments, runLocalQualityGates, } from '../local-quality-gates.js';
 import { FULL_METADATA_SELECTION_TYPES_HELP } from '../nested-metadata-registry.js';
 import { PROJECT_DEFAULT_KEYS } from '../project-defaults.js';
-import { performPromotionRun, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, resolvePromotionIdForWorkItem, } from '../promotion-run.js';
-import { runWorkTestLocalQualityGates } from '../stock-quality-gates.js';
+import { performPromotionRun, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, PromotionRunValidationError, resolveOrCreatePromotionForWorkItem, } from '../promotion-run.js';
+import { isApexOnlySelection, resolveQualityGateSelection } from '../quality-gates.js';
+import { listLocalQualityGates, runWorkTestLocalQualityGates } from '../stock-quality-gates.js';
 import { getUserContext } from '../user-context.js';
 import { resolveWorkItemId } from '../work-active.js';
-import { planWorkApexTestRun, recordWorkApexTestOutcome } from '../work-apex-test-failures.js';
-import { DEFAULT_APEX_TEST_WAIT_MINUTES, parseApexTestClassNames, runWorkApexTests, skippedWorkApexTestResult, validateApexTestWaitMinutes, WorkApexTestError, } from '../work-apex-test.js';
+import { executeWorkApexTestRun } from '../work-apex-test-failures.js';
+import { DEFAULT_APEX_TEST_WAIT_MINUTES, parseApexTestClassNames, validateApexTestWaitMinutes, WorkApexTestError, } from '../work-apex-test.js';
 import { buildWorkCommitRequest, normalizeWorkCommitInput, performWorkCommit, resolveWorkCommitPlatformExperience, WORK_COMMIT_ACTIONS, WORK_COMMIT_CHANGES_HELP, WORK_COMMIT_DEFAULT_TIMEOUT_SECONDS, WORK_COMMIT_METADATA_CATEGORY_HELP, } from '../work-commit.js';
 import { buildWorkCreatePayload } from '../work-defaults.js';
 import { normalizeWorkCustomFields, validateWorkMutationPayload, WORK_LONG_TEXT_MAX_LENGTH, WORK_SHORT_TEXT_MAX_LENGTH, } from '../work-flags.js';
 import { fetchWorkItems, fetchWorkItemWithOptions } from '../work-get.js';
 import { performWorkLocalCommit } from '../work-local-commit.js';
-import { reportLocalQualityGatesFailure, reportLocalQualityGatesOutcome, } from '../work-local-run-tests.js';
+import { reportApexGateRun, reportLocalQualityGatesFailure, reportLocalQualityGatesOutcome, } from '../work-local-run-tests.js';
 import { capturingWorkPushHooks, performWorkPush, resolveActiveFeatureWorkItem, resolveWorkPushContext, resolveWorkPushNeed, uploadCapturedPublishLogsBestEffort, } from '../work-push.js';
 import { performWorkSetNone } from '../work-set-none.js';
+import { WorkPromoteValidationError } from '../work-promote.js';
 import { isWorkSetWarning, parseWorkSetSelection, toWorkSetWarningResult, writeWorkSetWarningSelection, } from '../work-set-selection.js';
 import { reportSubmitUserStoriesAheadBehind } from '../work-submit-ahead-behind.js';
 import { waitForPendingCommitJobIfNeeded } from '../work-submit-wait.js';
@@ -403,11 +405,35 @@ async function workTest(args = {}) {
         throw new Error('Cloud quality gates are not implemented yet. Pass local: true or omit cloud to run project-root quality gates.');
     }
     parseQualityGatesEnvAssignments(args.env);
+    const selection = resolveQualityGateSelection({ all: args.all, gates: args.gates });
+    if (args.listGates === true) {
+        const catalog = await listLocalQualityGates();
+        return { gates: catalog.gates, local: true, qualityGates: { ran: false, skipped: false } };
+    }
+    if (isApexOnlySelection(selection)) {
+        let apex;
+        try {
+            apex = await workTestApex({
+                apexTestClasses: args.apexTestClasses,
+                rerunFailedApexTests: args.rerunFailedApexTests,
+                wait: args.wait,
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkApexTestError) {
+                await reportApexGateRunBestEffort(error.result, true);
+            }
+            throw error;
+        }
+        await reportApexGateRunBestEffort(apex, false);
+        return { apex, local: true, qualityGates: { ran: apex.skipped !== true, skipped: false } };
+    }
     let qualityGates;
     try {
         qualityGates = await runWorkTestLocalQualityGates({
             apexTestClasses: args.apexTestClasses,
             env: args.env,
+            gates: selection.gates,
             onOutput() {
                 // Capture output for the tool result/error; do not stream to the MCP stdio transport.
             },
@@ -442,28 +468,22 @@ async function workTest(args = {}) {
         qualityGates,
     };
 }
-async function workTestApex(args) {
-    const classNames = parseApexTestClassNames(args.apexTestClasses);
-    const waitMinutes = validateApexTestWaitMinutes(args.wait ?? DEFAULT_APEX_TEST_WAIT_MINUTES);
-    const plan = await planWorkApexTestRun({
-        requestedClassNames: classNames,
-        rerunFailed: args.rerunFailedApexTests === true,
-    });
-    if (plan.kind === 'skip') {
-        return skippedWorkApexTestResult(waitMinutes);
-    }
+async function reportApexGateRunBestEffort(result, failed) {
     try {
-        const result = await runWorkApexTests({ classNames: plan.classNames, waitMinutes });
-        await recordWorkApexTestOutcome({ failed: false, result, userStory: plan.userStory });
-        return result;
+        const { workItem } = await requireFeatureBranchWorkItem();
+        await reportApexGateRun({ failed, result, workItem });
     }
-    catch (error) {
-        if (error instanceof WorkApexTestError) {
-            await recordWorkApexTestOutcome({ failed: true, result: error.result, userStory: plan.userStory });
-        }
-        throw error;
+    catch {
+        // Best-effort reporting; never mask the Apex outcome.
     }
 }
+async function workTestApex(args) {
+    return executeWorkApexTestRun({
+        requestedClassNames: parseApexTestClassNames(args.apexTestClasses),
+        rerunFailed: args.rerunFailedApexTests === true,
+        waitMinutes: validateApexTestWaitMinutes(args.wait ?? DEFAULT_APEX_TEST_WAIT_MINUTES),
+    });
+}
 function hasMcpSimpleCommitArgs(args) {
     return (args.action !== undefined ||
         args.metadataCategory !== undefined ||
@@ -579,21 +599,37 @@ async function cloudPromote(args = {}) {
         throw new Error('waitTimeout must be a positive integer.');
     }
     const workItemId = await resolveWorkItemId(args.id);
-    const promotionId = await resolvePromotionIdForWorkItem(workItemId, args.promotionId);
-    const result = await performPromotionRun({
-        deploymentStepIds: args.deploymentStepIds,
-        hooks: {
-            log() { },
-            withSpinner: async (_message, action) => action(),
-        },
-        ignoredMetadata: args.ignoredMetadata,
-        operation: args.deploy === true ? 'merge_and_deploy' : 'merge',
-        promotionId,
-        recreatePromotionBranch: args.recreatePromotionBranch,
-        timeoutSeconds: waitTimeout,
-        wait: args.wait ?? true,
-    });
-    return { ...result, workItemId };
+    let createdPromotion;
+    try {
+        const resolved = await resolveOrCreatePromotionForWorkItem(workItemId, args.promotionId);
+        createdPromotion = resolved.createdPromotion;
+        const promotionId = resolved.promotionId;
+        const result = await performPromotionRun({
+            deploymentStepIds: args.deploymentStepIds,
+            hooks: {
+                log() { },
+                withSpinner: async (_message, action) => action(),
+            },
+            ignoredMetadata: args.ignoredMetadata,
+            operation: args.deploy === true ? 'merge_and_deploy' : 'merge',
+            promotionId,
+            recreatePromotionBranch: args.recreatePromotionBranch,
+            timeoutSeconds: waitTimeout,
+            wait: args.wait ?? true,
+        });
+        return {
+            ...result,
+            ...(createdPromotion === undefined ? {} : { createdPromotion }),
+            workItemId,
+        };
+    }
+    catch (error) {
+        // Map validation errors to plain Error messages for MCP clients.
+        if (error instanceof PromotionRunValidationError || error instanceof WorkPromoteValidationError) {
+            throw new Error(error.message);
+        }
+        throw error;
+    }
 }
 /** Compatibility alias of agentia_work_submit with done=true. Prefer agentia_work_submit({ done: true }). */
 async function workDone(args = {}) {
@@ -646,7 +682,7 @@ const workMutationSchema = {
     plannedPoints: z.number().int().optional().describe('Planned points.'),
     priority: z.number().int().optional().describe('Priority.'),
     project: z.string().optional().describe('Project ID.'),
-    recordType: z.string().optional().describe('Record type.'),
+    recordType: z.string().optional().describe('Record type DeveloperName.'),
     releaseId: z.string().optional().describe('Release ID.'),
     soThat: z.string().max(WORK_SHORT_TEXT_MAX_LENGTH).optional().describe('User story "so that" clause (maximum 255 characters).'),
     sourceCredential: z.string().optional().describe('Source credential ID. When set, sourceEnvironment is sent as null so Salesforce assigns the environment from the credential.'),
@@ -686,7 +722,7 @@ export function registerAgentiaMcpWorkTools(server) {
                 .boolean()
                 .optional()
                 .describe('When true, also include the Story committed metadata list as committedMetadata in the result.'),
-            id: z.string().optional().describe('User story Id. Defaults to the active work item from work set.'),
+            id: z.string().optional().describe('User story Id or name. Defaults to the active work item from work set.'),
         },
         title: 'Agentia Work Get',
     }, (args) => safelyHandleTool(() => workGet(args || {})));
@@ -699,14 +735,14 @@ export function registerAgentiaMcpWorkTools(server) {
         description: 'Update a Copado user story by Id via the CICD gateway. Omit Id to use the active work item from work set.',
         inputSchema: {
             ...workMutationSchema,
-            id: z.string().optional().describe('User story Id. Defaults to the active work item from work set.'),
+            id: z.string().optional().describe('User story Id or name. Defaults to the active work item from work set.'),
         },
         title: 'Agentia Work Update',
     }, (args) => safelyHandleTool(() => workUpdate(args)));
     server.registerTool('agentia_work_delete', {
         description: 'Delete a Copado user story by Id via the CICD gateway.',
         inputSchema: {
-            id: z.string().describe('User story Id.'),
+            id: z.string().describe('User story Id or name.'),
         },
         title: 'Agentia Work Delete',
     }, (args) => safelyHandleTool(() => workDelete(args)));
@@ -799,7 +835,7 @@ export function registerAgentiaMcpWorkTools(server) {
         promotionId: z
             .string()
             .optional()
-            .describe('Explicit 18-character Promotion ID when the User Story belongs to multiple promotions.'),
+            .describe('Explicit 18-character Promotion ID when the User Story belongs to multiple promotions. Used as is; never creates a promotion.'),
         recreatePromotionBranch: z.boolean().optional().describe('Recreate the promotion branch before execution.'),
         wait: z.boolean().optional().describe('Poll all created executions to terminal status. Defaults to true.'),
         waitTimeout: z
@@ -825,7 +861,7 @@ export function registerAgentiaMcpWorkTools(server) {
         title: 'Agentia Work Commit',
     }, (args) => safelyHandleTool(() => workCommit(args || {})));
     server.registerTool('agentia_cloud_promote', {
-        description: 'Resolve a Promotion from an explicit or active User Story, then preflight, start, and optionally wait for the cloud promotion.',
+        description: 'Resolve a Promotion from an explicit or active User Story, then preflight, start, and optionally wait for the cloud promotion. When no promotion contains the story, creates a forward Draft promotion, adds the story, then runs. Returns createdPromotion when a promotion was created. promotionId is used as is and never creates a promotion.',
         inputSchema: cloudPromoteInputSchema,
         title: 'Agentia Cloud Promote',
     }, (args) => safelyHandleTool(() => cloudPromote(args || {})));
@@ -853,8 +889,12 @@ export function registerAgentiaMcpWorkTools(server) {
         title: 'Agentia Work Submit',
     }, (args) => safelyHandleTool(() => workSubmit(args || {})));
     server.registerTool('agentia_work_test', {
-        description: 'Run quality gates for the current work item. With local=true (the default when cloud is omitted), runs project-root .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows) when present. When no project script exists, warns and runs the stock Agentia setup sample from a temporary file. With cloud=true, runs remote Copado quality gates (not implemented yet). Optional env is an array of NAME=value strings injected into the quality-gate script environment (same as CLI -e/--env).',
+        description: 'Run quality gates for the current work item. With local=true (the default when cloud is omitted), runs project-root .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows) when present. When no project script exists, warns and runs the stock Agentia setup sample from a temporary file. With cloud=true, runs remote Copado quality gates (not implemented yet). By default every gate runs; pass gates to run a subset (scripts declare gates with `# agentia-gate: <id> - <description>`) or listGates to list them. Optional env is an array of NAME=value strings injected into the quality-gate script environment (same as CLI -e/--env).',
         inputSchema: {
+            all: z
+                .boolean()
+                .optional()
+                .describe('Run every gate in the quality-gates script (default when gates is omitted). Mutually exclusive with gates.'),
             apexTestClasses: z
                 .string()
                 .optional()
@@ -867,6 +907,14 @@ export function registerAgentiaMcpWorkTools(server) {
                 .array(z.string())
                 .optional()
                 .describe('Extra environment variables for the quality-gate script as NAME=value strings (same as CLI -e/--env). Applied before reserved AGENTIA_APEX_* variables.'),
+            gates: z
+                .array(z.string())
+                .optional()
+                .describe('Run only these gate ids (standard: apex, lint, lwc; or custom ids declared in the script). Exported as AGENTIA_GATES. Only ["apex"] skips the script and runs the Apex tests directly.'),
+            listGates: z
+                .boolean()
+                .optional()
+                .describe('List the gates declared in the quality-gates script (or the stock sample) and return without running anything.'),
             local: z
                 .boolean()
                 .optional()
@@ -874,12 +922,17 @@ export function registerAgentiaMcpWorkTools(server) {
             rerunFailedApexTests: z
                 .boolean()
                 .optional()
-                .describe('Pass AGENTIA_APEX_RERUN_FAILED=--rerun-failed-apex-tests to local quality gates so sample scripts forward that flag to work test apex.'),
+                .describe('Pass AGENTIA_APEX_RERUN_FAILED=--rerun-failed-apex-tests to local quality gates so sample scripts forward that flag to the apex gate.'),
+            wait: z
+                .number()
+                .int()
+                .optional()
+                .describe(`Minutes to wait for Apex test results when gates is ["apex"]. Defaults to ${DEFAULT_APEX_TEST_WAIT_MINUTES}.`),
         },
         title: 'Agentia Work Test',
     }, (args) => safelyHandleTool(() => workTest(args || {})));
     server.registerTool('agentia_work_test_apex', {
-        description: 'Run specified Apex test classes via Salesforce CLI (`sf apex run test`) with code coverage. Usually run from project-root local quality gates (`.agentia_quality_gates.sh` / `.agentia_quality_gates.cmd`) when those scripts are configured. When apexTestClasses is omitted or empty, skips Salesforce CLI and returns skipped=true. Failed runs save `.agentia/apex.tests.<user-story>.json`; successful runs delete that file. rerunFailedApexTests runs the previously failed classes. Returns the test-run summary when the run passes. Failed runs include failing tests with Message and StackTrace.',
+        description: 'Run specified Apex test classes via Salesforce CLI (`sf apex run test`) with code coverage. Equivalent to agentia_work_test with gates ["apex"]. When apexTestClasses is omitted or empty, skips Salesforce CLI and returns skipped=true. Failed runs save `.agentia/apex.tests.<user-story>.json`; successful runs delete that file. rerunFailedApexTests runs the previously failed classes. Returns the test-run summary when the run passes. Failed runs include failing tests with Message and StackTrace.',
         inputSchema: {
             apexTestClasses: z
                 .string()

package/dist/lib/promotion-queue.js

@@ -0,0 +1,5 @@
+import {modules} from './runtime.js';
+const fetchPromotionQueue = modules["promotion-queue.js"]["fetchPromotionQueue"]
+const formatPromotionQueueTable = modules["promotion-queue.js"]["formatPromotionQueueTable"]
+const removePromotionQueueItems = modules["promotion-queue.js"]["removePromotionQueueItems"]
+export {fetchPromotionQueue, formatPromotionQueueTable, removePromotionQueueItems};

package/dist/lib/promotion-run.js

@@ -1,4 +1,5 @@
 import {modules} from './runtime.js';
+const NoPromotionForUserStoryError = modules["promotion-run.js"]["NoPromotionForUserStoryError"]
 const PROMOTION_OPERATIONS = modules["promotion-run.js"]["PROMOTION_OPERATIONS"]
 const PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS = modules["promotion-run.js"]["PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS"]
 const PromotionRunIncompleteResponseError = modules["promotion-run.js"]["PromotionRunIncompleteResponseError"]
@@ -22,6 +23,8 @@ const promotionRunErrorJson = modules["promotion-run.js"]["promotionRunErrorJson
 const promotionValidateResolutionEndpoint = modules["promotion-run.js"]["promotionValidateResolutionEndpoint"]
 const requirePromotionId = modules["promotion-run.js"]["requirePromotionId"]
 const resetPromotionRunSleepForTests = modules["promotion-run.js"]["resetPromotionRunSleepForTests"]
+const resolveOrCreatePromotionForWorkItem = modules["promotion-run.js"]["resolveOrCreatePromotionForWorkItem"]
 const resolvePromotionIdForWorkItem = modules["promotion-run.js"]["resolvePromotionIdForWorkItem"]
 const setPromotionRunSleepForTests = modules["promotion-run.js"]["setPromotionRunSleepForTests"]
-export {PROMOTION_OPERATIONS, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, PromotionRunIncompleteResponseError, PromotionRunJobFailedError, PromotionRunTimeoutError, PromotionRunValidationError, assertPromotionContextReady, formatPromotionRunResult, isPromotionRunExecutionError, parseIgnoredMetadataJson, performPromotionResume, performPromotionRun, promotionContextEndpoint, promotionDeploymentStepsEndpoint, promotionIgnoredMetadataEndpoint, promotionJobMonitorEndpoint, promotionResumeEndpoint, promotionRunDetailEndpoint, promotionRunEndpoint, promotionRunErrorJson, promotionValidateResolutionEndpoint, requirePromotionId, resetPromotionRunSleepForTests, resolvePromotionIdForWorkItem, setPromotionRunSleepForTests};
+const waitForPromotionDeploymentExecution = modules["promotion-run.js"]["waitForPromotionDeploymentExecution"]
+export {NoPromotionForUserStoryError, PROMOTION_OPERATIONS, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, PromotionRunIncompleteResponseError, PromotionRunJobFailedError, PromotionRunTimeoutError, PromotionRunValidationError, assertPromotionContextReady, formatPromotionRunResult, isPromotionRunExecutionError, parseIgnoredMetadataJson, performPromotionResume, performPromotionRun, promotionContextEndpoint, promotionDeploymentStepsEndpoint, promotionIgnoredMetadataEndpoint, promotionJobMonitorEndpoint, promotionResumeEndpoint, promotionRunDetailEndpoint, promotionRunEndpoint, promotionRunErrorJson, promotionValidateResolutionEndpoint, requirePromotionId, resetPromotionRunSleepForTests, resolveOrCreatePromotionForWorkItem, resolvePromotionIdForWorkItem, setPromotionRunSleepForTests, waitForPromotionDeploymentExecution};

package/dist/lib/promotion-status.js

@@ -0,0 +1,12 @@
+import {modules} from './runtime.js';
+const buildPromotionActionNeeded = modules["promotion-status.js"]["buildPromotionActionNeeded"]
+const buildPromotionStatusSnapshot = modules["promotion-status.js"]["buildPromotionStatusSnapshot"]
+const fetchPromotionStatus = modules["promotion-status.js"]["fetchPromotionStatus"]
+const formatPromotionStatus = modules["promotion-status.js"]["formatPromotionStatus"]
+const isManualTaskStep = modules["promotion-status.js"]["isManualTaskStep"]
+const isPendingManualTaskStep = modules["promotion-status.js"]["isPendingManualTaskStep"]
+const pickCurrentJobStep = modules["promotion-status.js"]["pickCurrentJobStep"]
+const pickPendingManualTaskStep = modules["promotion-status.js"]["pickPendingManualTaskStep"]
+const resolvePromotionStatusJobId = modules["promotion-status.js"]["resolvePromotionStatusJobId"]
+const toPromotionStatusStep = modules["promotion-status.js"]["toPromotionStatusStep"]
+export {buildPromotionActionNeeded, buildPromotionStatusSnapshot, fetchPromotionStatus, formatPromotionStatus, isManualTaskStep, isPendingManualTaskStep, pickCurrentJobStep, pickPendingManualTaskStep, resolvePromotionStatusJobId, toPromotionStatusStep};

package/dist/lib/quality-gates.js

@@ -0,0 +1,13 @@
+import {modules} from './runtime.js';
+const AGENTIA_GATES_ALL = modules["quality-gates.js"]["AGENTIA_GATES_ALL"]
+const AGENTIA_GATES_ENV = modules["quality-gates.js"]["AGENTIA_GATES_ENV"]
+const APEX_QUALITY_GATE_ID = modules["quality-gates.js"]["APEX_QUALITY_GATE_ID"]
+const STANDARD_QUALITY_GATE_IDS = modules["quality-gates.js"]["STANDARD_QUALITY_GATE_IDS"]
+const UnknownQualityGateError = modules["quality-gates.js"]["UnknownQualityGateError"]
+const formatDeclaredQualityGates = modules["quality-gates.js"]["formatDeclaredQualityGates"]
+const isApexOnlySelection = modules["quality-gates.js"]["isApexOnlySelection"]
+const parseDeclaredQualityGates = modules["quality-gates.js"]["parseDeclaredQualityGates"]
+const parseQualityGateIds = modules["quality-gates.js"]["parseQualityGateIds"]
+const qualityGatesEnvValue = modules["quality-gates.js"]["qualityGatesEnvValue"]
+const resolveQualityGateSelection = modules["quality-gates.js"]["resolveQualityGateSelection"]
+export {AGENTIA_GATES_ALL, AGENTIA_GATES_ENV, APEX_QUALITY_GATE_ID, STANDARD_QUALITY_GATE_IDS, UnknownQualityGateError, formatDeclaredQualityGates, isApexOnlySelection, parseDeclaredQualityGates, parseQualityGateIds, qualityGatesEnvValue, resolveQualityGateSelection};

package/dist/lib/repository-list.js

@@ -0,0 +1,3 @@
+import {modules} from './runtime.js';
+const fetchRepositories = modules["repository-list.js"]["fetchRepositories"]
+export {fetchRepositories};