@copado/agentia-cli 1.1.0 → 1.3.0

package/dist/lib/mcp/tools.js

@@ -2,23 +2,26 @@
 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';
 import { CICD_REGIONS } from '../cicd-region.js';
 import { credentialLabel, } from '../credential-store.js';
 import { readDefaults, readLastWorkItem, resolveDefaults, unsetDefaults, writeDefaults, } from '../defaults-store.js';
-import { runEnvironmentAuthStatus } from '../environment-auth-status.js';
+import { runCredentialAuthStatus, runEnvironmentAuthStatus } from '../environment-auth-status.js';
 import { collectCredentialUpdateFlagKeys, validateCredentialName } from '../environment-credential-flags.js';
-import { createEnvironmentCredential, listEnvironmentCredentials, resolveEnvironmentOrgType, sanitizeEnvironment, updateEnvironmentCredential, } from '../environment-credential-operations.js';
+import { createEnvironmentCredential, listCredentials, resolveEnvironmentOrgType, sanitizeCredentialListItem, sanitizeEnvironment, updateCredentialById, } from '../environment-credential-operations.js';
 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 { 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 { fetchPromotionQueue, removePromotionQueueItems } from '../promotion-queue.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';
@@ -58,6 +61,7 @@ import { agentiaMcpAiToolHandlers, registerAgentiaMcpAiTools } from './ai-tools.
 import { agentiaMcpDataToolHandlers, registerAgentiaMcpDataTools } from './data-tools.js';
 import { agentiaMcpDeploymentStepToolHandlers, registerAgentiaMcpDeploymentStepTools } from './deployment-step-tools.js';
 import { agentiaMcpHealthCheckToolHandlers, registerAgentiaMcpHealthCheckTools } from './health-check-tools.js';
+import { agentiaMcpPipelineAutomationQualityToolHandlers, registerAgentiaMcpPipelineAutomationQualityTools, } from './pipeline-automation-quality-tools.js';
 import { safelyHandleTool, wrapMcpToolHandlers } from './result.js';
 import { agentiaMcpTestingToolHandlers, registerAgentiaMcpTestingTools } from './testing-tools.js';
 import { agentiaMcpWorkToolHandlers, registerAgentiaMcpWorkTools } from './work-tools.js';
@@ -203,9 +207,12 @@ async function credentialCreate(args) {
     });
     return { credential };
 }
-async function credentialList(args) {
-    const credentials = await listEnvironmentCredentials(assertRequired(args.environmentId, 'environmentId'));
-    return { credentials };
+async function credentialList(args = {}) {
+    const page = await listCredentials(args);
+    return mcpPaginatedListPayload('credentials', {
+        ...page,
+        data: page.data.map((credential) => sanitizeCredentialListItem(credential)),
+    });
 }
 async function credentialUpdate(args) {
     const selectedKeys = collectCredentialUpdateFlagKeys({
@@ -219,15 +226,17 @@ async function credentialUpdate(args) {
     if (nameError !== undefined) {
         throw new Error(nameError);
     }
-    const orgType = await resolveEnvironmentOrgType(assertRequired(args.environmentId, 'environmentId'));
-    const credential = await updateEnvironmentCredential({
+    const credential = await updateCredentialById({
         credentialId: assertRequired(args.id, 'id'),
         defaultCredential: args.default,
-        environmentId: args.environmentId,
         name: args.name,
-        orgType,
     });
-    return { credential };
+    return { credential: sanitizeCredentialListItem(credential) };
+}
+async function credentialAuthStatus(args) {
+    return runCredentialAuthStatus({
+        credentialId: assertRequired(args.id, 'id'),
+    });
 }
 async function jobList(args) {
     const filters = {
@@ -280,6 +289,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));
 }
@@ -969,44 +984,70 @@ async function metadataContentCompare(args) {
         target: targetSide,
     };
 }
-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'),
+async function metadataExplore(args) {
+    const body = await buildAiMetadataToolRequest({
+        action: assertRequired(args.action, 'action'),
+        'apex-unit-tests': args.apexUnitTests,
+        // Deferred write/deploy flags:
+        // 'async-id': args.asyncId,
+        // 'metadata-files': args.metadataFiles,
+        // 'organization-name': args.organizationName,
+        // 'test-level': args.testLevel,
+        // 'validate-only': args.validateOnly,
+        'credential-id': args.credentialId,
+        endpoint: args.endpoint,
+        'full-name': args.fullName,
+        'object-type': args.objectType,
+        pattern: args.pattern,
+        'session-id': args.sessionId,
+    });
+    const output = await callAiMetadataTool(body);
+    return {
+        ...(body.credentialId === undefined ? {} : { credentialId: body.credentialId }),
+        output,
     };
-    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) {
@@ -1048,9 +1089,14 @@ async function authSet(args) {
     return { ...(result.baseUrl === undefined ? {} : { baseUrl: result.baseUrl }), stored: result.stored };
 }
 async function environmentAuthStatus(args) {
+    const environmentId = typeof args.id === 'string' ? args.id.trim() : '';
+    const credentialId = typeof args.credentialId === 'string' ? args.credentialId.trim() : '';
+    if (environmentId.length === 0 && credentialId.length === 0) {
+        throw new Error('Provide id (environment ID) or credentialId.');
+    }
     return runEnvironmentAuthStatus({
-        credentialId: args.credentialId,
-        environmentId: assertRequired(args.id, 'id'),
+        credentialId: credentialId.length > 0 ? credentialId : undefined,
+        environmentId: environmentId.length > 0 ? environmentId : undefined,
     });
 }
 async function jobLogGet(args) {
@@ -1249,8 +1295,10 @@ export const agentiaMcpToolHandlers = wrapMcpToolHandlers({
     ...agentiaMcpDataToolHandlers,
     ...agentiaMcpDeploymentStepToolHandlers,
     ...agentiaMcpHealthCheckToolHandlers,
+    ...agentiaMcpPipelineAutomationQualityToolHandlers,
     authGet,
     authSet,
+    credentialAuthStatus,
     credentialCreate,
     credentialList,
     credentialUpdate,
@@ -1273,6 +1321,8 @@ export const agentiaMcpToolHandlers = wrapMcpToolHandlers({
     jobList,
     jobLogGet,
     jobPause,
+    promotionQueueList,
+    promotionQueueRemove,
     jobResultFileGet,
     jobResultFileList,
     jobResume,
@@ -1280,6 +1330,7 @@ export const agentiaMcpToolHandlers = wrapMcpToolHandlers({
     metadataContentCompare,
     metadataContentGet,
     metadataDependencyList,
+    metadataExplore,
     metadataIndexCompare,
     metadataList,
     metadataRefreshDeleted,
@@ -1426,6 +1477,7 @@ export function registerAgentiaMcpTools(server) {
     registerAgentiaMcpDataTools(server);
     registerAgentiaMcpDeploymentStepTools(server);
     registerAgentiaMcpHealthCheckTools(server);
+    registerAgentiaMcpPipelineAutomationQualityTools(server);
     registerAgentiaMcpTestingTools(server);
     server.registerTool('agentia_environment_list', {
         description: 'List Copado environments via the CICD gateway.',
@@ -1472,22 +1524,29 @@ export function registerAgentiaMcpTools(server) {
         title: 'Agentia Credential Create',
     }, (args) => safelyHandleTool(() => credentialCreate(args)));
     server.registerTool('agentia_credential_list', {
-        description: 'List credentials for a Copado environment via the CICD gateway.',
+        description: 'List Copado credentials via the CICD gateway, optionally filtered by name.',
         inputSchema: {
-            environmentId: z.string().describe('Copado environment Id or name.'),
+            name: z.string().optional().describe('Filter credentials by name (partial match).'),
+            ...listPaginationZodFields,
         },
         title: 'Agentia Credential List',
-    }, (args) => safelyHandleTool(() => credentialList(args)));
+    }, (args) => safelyHandleTool(() => credentialList(args || {})));
     server.registerTool('agentia_credential_update', {
-        description: 'Update a Copado environment credential by Id via the CICD gateway.',
+        description: 'Update a Copado credential by Id via the CICD gateway.',
         inputSchema: {
             default: z.boolean().optional().describe('Mark this credential as the environment default.'),
-            environmentId: z.string().describe('Copado environment Id.'),
             id: z.string().describe('Copado credential Id.'),
             name: z.string().optional().describe('Credential name.'),
         },
         title: 'Agentia Credential Update',
     }, (args) => safelyHandleTool(() => credentialUpdate(args)));
+    server.registerTool('agentia_credential_auth_status', {
+        description: 'Validate a Copado credential by Id through the CICD gateway.',
+        inputSchema: {
+            id: z.string().describe('Copado credential Id.'),
+        },
+        title: 'Agentia Credential Auth Status',
+    }, (args) => safelyHandleTool(() => credentialAuthStatus(args)));
     server.registerTool('agentia_promotion_list', {
         description: 'List Copado promotions via the CICD gateway.',
         inputSchema: promotionListSchema,
@@ -1597,6 +1656,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: {
@@ -1801,12 +1873,12 @@ export function registerAgentiaMcpTools(server) {
     }, (args) => safelyHandleTool(() => projectDefaultUnset(args || {})));
     registerAgentiaMcpWorkTools(server);
     server.registerTool('agentia_metadata_list', {
-        description: 'Search the Copado metadata index via the CICD gateway.',
+        description: 'Search the Copado metadata index.',
         inputSchema: {
             avoidSourceTracking: z
                 .boolean()
                 .optional()
-                .describe('Pass avoidSourceTracking=true to the gateway index route.'),
+                .describe('Pass avoidSourceTracking=true to the index route.'),
             changeDateFrom: z
                 .string()
                 .optional()
@@ -1820,7 +1892,7 @@ export function registerAgentiaMcpTools(server) {
             moduleType: z.enum(MODULE_TYPES).optional().describe('Optional addon module type.'),
             orderDirection: z.enum(ORDER_DIRECTIONS).optional().describe('Sort direction for last modified date.'),
             pipelineId: z.string().describe('Pipeline Id.'),
-            platformExperience: z.enum(PLATFORM_EXPERIENCES).optional().describe('Gateway platform experience header.'),
+            platformExperience: z.enum(PLATFORM_EXPERIENCES).optional().describe('Platform experience header.'),
             source: z.enum(INDEX_SOURCES).optional().describe('Index source filter.'),
             sourceCredentialId: z.string().describe('Source org credential Id.'),
             sourceOrgId: z.string().describe('Source org Id.'),
@@ -1828,8 +1900,44 @@ export function registerAgentiaMcpTools(server) {
         },
         title: 'Agentia Metadata List',
     }, (args) => safelyHandleTool(() => metadataList(args)));
+    server.registerTool('agentia_metadata_explore', {
+        description: 'Explore Salesforce metadata through Org Intelligence. Uses the project default credential when credentialId is omitted; otherwise pass credentialId, or both sessionId and endpoint. Returns YAML tool output.',
+        inputSchema: {
+            action: z
+                .enum(AI_METADATA_ACTIONS)
+                .describe('Metadata action: list, search, read_documentation, describe_type, read, find_references, run_apex_tests.'),
+            apexUnitTests: z
+                .string()
+                .optional()
+                .describe('Comma-separated Apex test classes. Required for run_apex_tests.'),
+            // Deferred write/deploy MCP fields (re-add with AI_METADATA_ACTIONS when shipping mutate):
+            // asyncId, metadataFiles, organizationName, testLevel, validateOnly
+            credentialId: z
+                .string()
+                .optional()
+                .describe('Copado credential Id. Defaults to the CICD project default credential when set. Exclusive with sessionId+endpoint.'),
+            endpoint: z
+                .string()
+                .optional()
+                .describe('Salesforce instance URL used with sessionId when credentialId is omitted.'),
+            fullName: z
+                .string()
+                .optional()
+                .describe('Fully qualified metadata name (required for read).'),
+            objectType: z.string().optional().describe('Metadata type, for example ApexClass or CustomObject.'),
+            pattern: z
+                .string()
+                .optional()
+                .describe('Wildcard pattern for list/search (name without namespace). Defaults to *.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Salesforce session Id used with endpoint when credentialId is omitted.'),
+        },
+        title: 'Agentia Metadata Explore',
+    }, (args) => safelyHandleTool(() => metadataExplore(args)));
     server.registerTool('agentia_metadata_content_get', {
-        description: 'Retrieve metadata file content via the CICD gateway.',
+        description: 'Retrieve metadata file content.',
         inputSchema: {
             apiName: z.string().describe('Metadata API name.'),
             branch: z.string().optional().describe('Git branch when source is REPOSITORY or GIT_MIRROR.'),
@@ -1844,7 +1952,7 @@ export function registerAgentiaMcpTools(server) {
         title: 'Agentia Metadata Content Get',
     }, (args) => safelyHandleTool(() => metadataContentGet(args)));
     server.registerTool('agentia_metadata_index_compare', {
-        description: 'Compare metadata between orgs or Git branches via the CICD gateway.',
+        description: 'Compare metadata between orgs or Git branches.',
         inputSchema: {
             comparisonMode: z.enum(COMPARISON_MODES).describe('Comparison mode.'),
             filterType: z.string().optional().describe('Optional metadata type filter, for example ApexClass.'),
@@ -1874,19 +1982,44 @@ export function registerAgentiaMcpTools(server) {
         title: 'Agentia Metadata Content Compare',
     }, (args) => safelyHandleTool(() => metadataContentCompare(args)));
     server.registerTool('agentia_metadata_dependency_list', {
-        description: 'Retrieve metadata dependencies via the CICD gateway.',
+        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('Gateway 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)));
@@ -1918,10 +2051,13 @@ export function registerAgentiaMcpTools(server) {
         title: 'Agentia Auth Set',
     }, (args) => safelyHandleTool(() => authSet(args)));
     server.registerTool('agentia_environment_auth_status', {
-        description: 'Validate an environment credential through the CICD gateway.',
+        description: 'Validate an environment credential through the CICD gateway. Provide id, or credentialId alone to resolve the environment from the credential.',
         inputSchema: {
-            credentialId: z.string().optional().describe('Credential ID when selection is ambiguous.'),
-            id: z.string().describe('Copado environment ID.'),
+            credentialId: z
+                .string()
+                .optional()
+                .describe('Credential ID; when id is omitted, resolves the environment from the credential.'),
+            id: z.string().optional().describe('Copado environment ID (optional when credentialId is provided).'),
         },
         title: 'Agentia Environment Auth Status',
     }, (args) => safelyHandleTool(() => environmentAuthStatus(args)));
@@ -2267,14 +2403,14 @@ export function registerAgentiaMcpTools(server) {
         title: 'Agentia Promotion Conflict Unresolve',
     }, (args) => safelyHandleTool(() => promotionConflictUnresolve(args)));
     server.registerTool('agentia_metadata_refresh_run', {
-        description: 'Trigger a metadata index refresh via the CICD gateway.',
+        description: 'Trigger a metadata index refresh.',
         inputSchema: {
             all: z.boolean().optional().describe('Replace the metadata index instead of merging it.'),
             env: z.string().describe('Environment ID used to resolve source configuration.'),
             gitFiles: z.array(z.string()).optional().describe('Git file paths to refresh.'),
             moduleType: z.enum(MODULE_TYPES).optional().describe('Optional addon module type.'),
             pipelineId: z.string().optional().describe('Optional pipeline ID.'),
-            platformExperience: z.enum(PLATFORM_EXPERIENCES).optional().describe('Gateway platform experience header.'),
+            platformExperience: z.enum(PLATFORM_EXPERIENCES).optional().describe('Platform experience header.'),
             refreshMode: z.string().optional().describe('Optional refresh mode.'),
             selectedName: z.string().optional().describe('Selected metadata API name.'),
             selectedType: z.string().optional().describe('Selected metadata type.'),
@@ -2285,16 +2421,16 @@ export function registerAgentiaMcpTools(server) {
         title: 'Agentia Metadata Refresh Run',
     }, (args) => safelyHandleTool(() => metadataRefreshRun(args)));
     server.registerTool('agentia_metadata_refresh_status', {
-        description: 'Get metadata index refresh status via the CICD gateway.',
+        description: 'Get metadata index refresh status.',
         inputSchema: {
             jobId: z.string().describe('Metadata refresh event ID.'),
             moduleType: z.enum(MODULE_TYPES).optional().describe('Addon module type used by the refresh.'),
-            platformExperience: z.enum(PLATFORM_EXPERIENCES).optional().describe('Gateway platform experience header.'),
+            platformExperience: z.enum(PLATFORM_EXPERIENCES).optional().describe('Platform experience header.'),
         },
         title: 'Agentia Metadata Refresh Status',
     }, (args) => safelyHandleTool(() => metadataRefreshStatus(args)));
     server.registerTool('agentia_metadata_refresh_deleted', {
-        description: 'Refresh deleted metadata index entries via the CICD gateway.',
+        description: 'Refresh deleted metadata index entries.',
         inputSchema: {
             env: z.string().describe('Environment ID used to resolve the source credential.'),
             moduleType: z.enum(MODULE_TYPES).optional().describe('Optional addon module type.'),

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

@@ -17,7 +17,7 @@ import { planWorkApexTestRun, recordWorkApexTestOutcome } from '../work-apex-tes
 import { DEFAULT_APEX_TEST_WAIT_MINUTES, parseApexTestClassNames, runWorkApexTests, skippedWorkApexTestResult, 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 { validateWorkMutationPayload, WORK_LONG_TEXT_MAX_LENGTH, WORK_SHORT_TEXT_MAX_LENGTH, } from '../work-flags.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';
@@ -54,6 +54,7 @@ const WORK_MUTATION_PAYLOAD_KEYS = [
     'assignee',
     'cancellationReason',
     'closeDate',
+    'customFields',
     'epic',
     'excludedFromCbm',
     'feature',
@@ -80,7 +81,12 @@ function buildWorkMutationPayloadFromArgs(args) {
     for (const key of WORK_MUTATION_PAYLOAD_KEYS) {
         const value = args[key];
         if (value !== undefined) {
-            Object.assign(payload, { [key]: value });
+            if (key === 'customFields') {
+                Object.assign(payload, { customFields: normalizeWorkCustomFields(value) });
+            }
+            else {
+                Object.assign(payload, { [key]: value });
+            }
         }
     }
     return applySourceCredentialEnvironmentRule(payload);
@@ -617,6 +623,10 @@ const skipNestedMetadataDetectionSchema = z
     .boolean()
     .optional()
     .describe('Do not detect the nested metadata changed across the branch. Also configurable via skipNestedMetadataDetection in .agentia/config.json or .agentia/config.user.json.');
+const workCustomFieldWriteSchema = z.object({
+    apiName: z.string().min(1).describe('Salesforce subscriber custom field API name (for example JIRA_Key__c).'),
+    value: z.unknown().optional().describe('Field value to write (string, number, boolean, null, or multipicklist string).'),
+});
 const workMutationSchema = {
     acceptanceCriteria: z.string().max(WORK_SHORT_TEXT_MAX_LENGTH).optional().describe('Acceptance criteria (maximum 255 characters).'),
     actualPoints: z.number().int().optional().describe('Actual points.'),
@@ -624,6 +634,10 @@ const workMutationSchema = {
     assignee: z.string().optional().describe('Assignee ID.'),
     cancellationReason: z.string().optional().describe('Cancellation reason.'),
     closeDate: z.string().optional().describe('Close date.'),
+    customFields: z
+        .array(workCustomFieldWriteSchema)
+        .optional()
+        .describe('Subscriber custom fields to write as [{ apiName, value }]. Omit for packaged-only create/update. Duplicate apiNames are rejected.'),
     epic: z.string().optional().describe('Epic.'),
     excludedFromCbm: z.boolean().optional().describe('Exclude from CBM.'),
     feature: z.string().optional().describe('Feature.'),
@@ -697,7 +711,7 @@ export function registerAgentiaMcpWorkTools(server) {
         title: 'Agentia Work Delete',
     }, (args) => safelyHandleTool(() => workDelete(args)));
     server.registerTool('agentia_work_set', {
-        description: 'Set the active Copado work item and prepare a local feature/<user-story-name> branch. Requires a clean tracked working tree. Fetches the base branch from origin, fetches the feature branch when it exists on origin, then creates or checks out the feature branch from the remote feature when present, otherwise from the base. A gateway warning prints the message, skips git, clears lastBaseBranch/lastDevOrgBranch/lastPullRequestBaseUrl, and records lastWorkItemId/lastWorkItem/lastWorkItemTitle from the returned work item. After work/set returns, compares the Story source credential with the CICD project default: warns when the default or Story credential is missing, and warns without changing the Story when they differ (shows the current credential and environment; use work update to change it). With none=true, clears every last* key from config.user.json and checks out the previous lastBaseBranch when present, else main, else master, else stays put.',
+        description: 'Set the active Copado work item and prepare a local feature/<user-story-name> branch. Requires a clean tracked working tree. Fetches the base branch from origin, fetches the feature branch when it exists on origin, then creates or checks out the feature branch from the remote feature when present, otherwise from the base. A gateway warning prints the message, skips git, clears lastBaseBranch/lastDevOrgBranch/lastPullRequestBaseUrl, and records lastWorkItemId/lastWorkItem/lastWorkItemTitle from the returned work item. After work/set returns, compares the Story source credential with the CICD project default: warns when the Story credential is missing, skips comparison when a bound Story has no project default, and warns without changing the Story when they differ (shows the current credential and environment; use work update to change it). With none=true, clears every last* key from config.user.json and checks out the previous lastBaseBranch when present, else main, else master, else stays put.',
         inputSchema: {
             baseBranch: z
                 .string()
@@ -727,7 +741,7 @@ export function registerAgentiaMcpWorkTools(server) {
         skipNestedMetadataDetection: skipNestedMetadataDetectionSchema,
     };
     server.registerTool('agentia_work_publish', {
-        description: 'Publish the current feature/<lastWorkItem> branch and register commits with Copado. Requires a clean working tree, lastBaseBranch, and lastDevOrgBranch from config.user.json. Applies Copado environment-variable then yaml replacements when needed (yaml `-b` is the feature branch, matching Copado Commit), commits both as a single follow-up commit, sends one headless push changeListUpdate list of Action:MetadataType:MetadataName corrections (lastPermissionSelected and the permissions argument plus the nested metadata of the changed profiles and permission sets as RetrieveOnly so Copado registers that metadata with the Retrieve Only commit action, lastFullMetadataSelected and the fullMetadata argument plus brand-new nested parent files as fullMetadata, the ignored nested parents as unchanged, the nested metadata the branch deleted as Del, and the remaining nested metadata as Add). The changed profiles and permission sets themselves are never sent as corrections, so they stay in the change list and deploy only the permissions their RetrieveOnly entries select; brand-new nested parent files are sent as fullMetadata instead. Merges the feature branch into the recorded dev org branch after headless push. With dryRun=true, previews replacements and changeListUpdate, restores dirtied tracked files, and skips commit/push/lock/register/dev-org sync. Prefer this over agentia_work_push.',
+        description: 'Publish the current feature/<lastWorkItem> branch and register commits with Copado. Requires a clean working tree, lastBaseBranch, and lastDevOrgBranch from config.user.json. Applies Copado environment-variable then yaml replacements when needed (yaml `-b` is the feature branch, matching Copado Commit), commits both as a single follow-up commit, sends one headless push changeListUpdate list of Action:MetadataType:MetadataName corrections (lastPermissionSelected and the permissions argument plus the nested metadata of the changed profiles and permission sets as RetrieveOnly so Copado registers that metadata with the Retrieve Only commit action, lastFullMetadataSelected and the fullMetadata argument plus brand-new nested parent files as fullMetadata, the ignored nested parents as unchanged, the nested metadata the branch deleted as Delete, and the remaining nested metadata as Add). The changed profiles and permission sets themselves are never sent as corrections, so they stay in the change list and deploy only the permissions their RetrieveOnly entries select; brand-new nested parent files are sent as fullMetadata instead. Merges the feature branch into the recorded dev org branch after headless push. With dryRun=true, previews replacements and changeListUpdate, restores dirtied tracked files, and skips commit/push/lock/register/dev-org sync. Prefer this over agentia_work_push.',
         inputSchema: workPublishInputSchema,
         title: 'Agentia Work Publish',
     }, (args) => safelyHandleTool(() => workPublish(args || {})));

package/dist/lib/metadata-explore.js

@@ -0,0 +1,8 @@
+import {modules} from './runtime.js';
+const AI_METADATA_ACTIONS = modules["metadata-explore.js"]["AI_METADATA_ACTIONS"]
+const AI_METADATA_TOOL_ENDPOINT = modules["metadata-explore.js"]["AI_METADATA_TOOL_ENDPOINT"]
+const buildAiMetadataToolRequest = modules["metadata-explore.js"]["buildAiMetadataToolRequest"]
+const callAiMetadataTool = modules["metadata-explore.js"]["callAiMetadataTool"]
+const missingExploreCredentialError = modules["metadata-explore.js"]["missingExploreCredentialError"]
+const resolveExploreCredentialId = modules["metadata-explore.js"]["resolveExploreCredentialId"]
+export {AI_METADATA_ACTIONS, AI_METADATA_TOOL_ENDPOINT, buildAiMetadataToolRequest, callAiMetadataTool, missingExploreCredentialError, resolveExploreCredentialId};

package/dist/lib/network-error.js

@@ -0,0 +1,8 @@
+import {modules} from './runtime.js';
+const formatTransportNetworkError = modules["network-error.js"]["formatTransportNetworkError"]
+const gatewayTimeoutError = modules["network-error.js"]["gatewayTimeoutError"]
+const getTransportNetworkInfo = modules["network-error.js"]["getTransportNetworkInfo"]
+const isHttpGatewaySoftMiss = modules["network-error.js"]["isHttpGatewaySoftMiss"]
+const isTransportNetworkError = modules["network-error.js"]["isTransportNetworkError"]
+const throwFormattedTransportNetworkError = modules["network-error.js"]["throwFormattedTransportNetworkError"]
+export {formatTransportNetworkError, gatewayTimeoutError, getTransportNetworkInfo, isHttpGatewaySoftMiss, isTransportNetworkError, throwFormattedTransportNetworkError};

package/dist/lib/pipeline-automation-flags.js

@@ -0,0 +1,12 @@
+import {modules} from './runtime.js';
+const AUTOMATION_FILTER_CRITERIA_FLAG_DESCRIPTION = modules["pipeline-automation-flags.js"]["AUTOMATION_FILTER_CRITERIA_FLAG_DESCRIPTION"]
+const buildPipelineAutomationCreatePayload = modules["pipeline-automation-flags.js"]["buildPipelineAutomationCreatePayload"]
+const buildPipelineAutomationUpdatePayload = modules["pipeline-automation-flags.js"]["buildPipelineAutomationUpdatePayload"]
+const normalizeAutomationFilterCriteria = modules["pipeline-automation-flags.js"]["normalizeAutomationFilterCriteria"]
+const parseAutomationFilterCriteria = modules["pipeline-automation-flags.js"]["parseAutomationFilterCriteria"]
+const pipelineAutomationListFlags = modules["pipeline-automation-flags.js"]["pipelineAutomationListFlags"]
+const pipelineAutomationMutationFlags = modules["pipeline-automation-flags.js"]["pipelineAutomationMutationFlags"]
+const readAutomationFilterCriteriaFromFile = modules["pipeline-automation-flags.js"]["readAutomationFilterCriteriaFromFile"]
+const resolveAutomationFilterCriteria = modules["pipeline-automation-flags.js"]["resolveAutomationFilterCriteria"]
+const validateAutomationCreateControls = modules["pipeline-automation-flags.js"]["validateAutomationCreateControls"]
+export {AUTOMATION_FILTER_CRITERIA_FLAG_DESCRIPTION, buildPipelineAutomationCreatePayload, buildPipelineAutomationUpdatePayload, normalizeAutomationFilterCriteria, parseAutomationFilterCriteria, pipelineAutomationListFlags, pipelineAutomationMutationFlags, readAutomationFilterCriteriaFromFile, resolveAutomationFilterCriteria, validateAutomationCreateControls};

package/dist/lib/pipeline-automation-ops.js

@@ -0,0 +1,9 @@
+import {modules} from './runtime.js';
+const activatePipelineAutomationRule = modules["pipeline-automation-ops.js"]["activatePipelineAutomationRule"]
+const createPipelineAutomationRule = modules["pipeline-automation-ops.js"]["createPipelineAutomationRule"]
+const deactivatePipelineAutomationRule = modules["pipeline-automation-ops.js"]["deactivatePipelineAutomationRule"]
+const deletePipelineAutomationRule = modules["pipeline-automation-ops.js"]["deletePipelineAutomationRule"]
+const fetchPipelineAutomationRule = modules["pipeline-automation-ops.js"]["fetchPipelineAutomationRule"]
+const fetchPipelineAutomationRules = modules["pipeline-automation-ops.js"]["fetchPipelineAutomationRules"]
+const updatePipelineAutomationRule = modules["pipeline-automation-ops.js"]["updatePipelineAutomationRule"]
+export {activatePipelineAutomationRule, createPipelineAutomationRule, deactivatePipelineAutomationRule, deletePipelineAutomationRule, fetchPipelineAutomationRule, fetchPipelineAutomationRules, updatePipelineAutomationRule};

package/dist/lib/pipeline-automation-types.js

@@ -0,0 +1,18 @@
+import {modules} from './runtime.js';
+const AUTOMATION_CRITERIA_LOGICS = modules["pipeline-automation-types.js"]["AUTOMATION_CRITERIA_LOGICS"]
+const AUTOMATION_CRITERIA_MODES = modules["pipeline-automation-types.js"]["AUTOMATION_CRITERIA_MODES"]
+const AUTOMATION_CRITERIA_OPERATORS = modules["pipeline-automation-types.js"]["AUTOMATION_CRITERIA_OPERATORS"]
+const AUTOMATION_EXECUTION_TIMES = modules["pipeline-automation-types.js"]["AUTOMATION_EXECUTION_TIMES"]
+const AUTOMATION_PROMOTION_TRIGGERS = modules["pipeline-automation-types.js"]["AUTOMATION_PROMOTION_TRIGGERS"]
+const AUTOMATION_SCOPES = modules["pipeline-automation-types.js"]["AUTOMATION_SCOPES"]
+const AUTOMATION_SOURCE_ACTIONS = modules["pipeline-automation-types.js"]["AUTOMATION_SOURCE_ACTIONS"]
+const AUTOMATION_SOURCE_ACTION_STATUSES = modules["pipeline-automation-types.js"]["AUTOMATION_SOURCE_ACTION_STATUSES"]
+const formatPipelineAutomationRuleDetail = modules["pipeline-automation-types.js"]["formatPipelineAutomationRuleDetail"]
+const formatPipelineAutomationRuleTable = modules["pipeline-automation-types.js"]["formatPipelineAutomationRuleTable"]
+const normalizePipelineAutomationRule = modules["pipeline-automation-types.js"]["normalizePipelineAutomationRule"]
+const normalizePipelineAutomationRulesListPage = modules["pipeline-automation-types.js"]["normalizePipelineAutomationRulesListPage"]
+const pipelineAutomationRuleActivateEndpoint = modules["pipeline-automation-types.js"]["pipelineAutomationRuleActivateEndpoint"]
+const pipelineAutomationRuleDeactivateEndpoint = modules["pipeline-automation-types.js"]["pipelineAutomationRuleDeactivateEndpoint"]
+const pipelineAutomationRuleEndpoint = modules["pipeline-automation-types.js"]["pipelineAutomationRuleEndpoint"]
+const pipelineAutomationRulesEndpoint = modules["pipeline-automation-types.js"]["pipelineAutomationRulesEndpoint"]
+export {AUTOMATION_CRITERIA_LOGICS, AUTOMATION_CRITERIA_MODES, AUTOMATION_CRITERIA_OPERATORS, AUTOMATION_EXECUTION_TIMES, AUTOMATION_PROMOTION_TRIGGERS, AUTOMATION_SCOPES, AUTOMATION_SOURCE_ACTIONS, AUTOMATION_SOURCE_ACTION_STATUSES, formatPipelineAutomationRuleDetail, formatPipelineAutomationRuleTable, normalizePipelineAutomationRule, normalizePipelineAutomationRulesListPage, pipelineAutomationRuleActivateEndpoint, pipelineAutomationRuleDeactivateEndpoint, pipelineAutomationRuleEndpoint, pipelineAutomationRulesEndpoint};

package/dist/lib/pipeline-lifecycle-id.js

@@ -0,0 +1,3 @@
+import {modules} from './runtime.js';
+const assertSalesforceLifecycleId = modules["pipeline-lifecycle-id.js"]["assertSalesforceLifecycleId"]
+export {assertSalesforceLifecycleId};