@copado/agentia-cli 1.0.0-beta.1 → 1.0.0-beta.2

package/dist/lib/mcp/tool-annotations.js

@@ -0,0 +1,265 @@
+/**
+ * Standard MCP tool annotations for every Agentia MCP tool.
+ *
+ * Annotations are hints for MCP clients (auto-approve, confirmation prompts); they are not
+ * enforcement. Gateway authorization still applies. Only a few tools enforce their own `confirm` flag.
+ *
+ * Every tool is classified here explicitly. `test/lib/mcp/tool-annotations.test.ts` fails when a
+ * registered tool is missing from the table, so new tools must be classified when they are added.
+ */
+/** MCP spec: destructive means the tool may overwrite or remove existing state, not only add. */
+const CLASS_ANNOTATIONS = {
+    // Runs or triggers something with side effects; repeating it repeats the effect.
+    action: { destructiveHint: true, idempotentHint: false, readOnlyHint: false },
+    // Read-only but not repeatable (model output varies).
+    ask: { destructiveHint: false, idempotentHint: false, readOnlyHint: true },
+    // Purely additive; repeating it creates another record.
+    create: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
+    // Removes or resets state; repeating it has no further effect.
+    delete: { destructiveHint: true, idempotentHint: true, readOnlyHint: false },
+    read: { destructiveHint: false, idempotentHint: true, readOnlyHint: true },
+    // Overwrites existing state with the same result when repeated.
+    update: { destructiveHint: true, idempotentHint: true, readOnlyHint: false },
+};
+/** Triggers side effects (commit, promote, run, kill, ...). */
+const ACTION_TOOLS = [
+    'agentia_cloud_commit',
+    'agentia_cloud_promote',
+    'agentia_data_sync_apply',
+    'agentia_function_run',
+    'agentia_function_run_local',
+    'agentia_job_kill',
+    'agentia_job_pause',
+    'agentia_job_resume',
+    'agentia_job_run',
+    'agentia_metadata_refresh_deleted',
+    'agentia_metadata_refresh_run',
+    'agentia_promotion_run',
+    'agentia_testing_build_abort',
+    'agentia_testing_build_run',
+    'agentia_testing_job_run',
+    'agentia_testing_live_continue',
+    'agentia_testing_live_execute',
+    'agentia_testing_live_interrupt',
+    'agentia_testing_live_stop',
+    'agentia_testing_run',
+    'agentia_work_commit',
+    'agentia_work_done',
+    'agentia_work_publish',
+    'agentia_work_push',
+    'agentia_work_submit',
+    'agentia_work_test',
+    'agentia_work_test_apex',
+];
+/** Read-only, non-repeatable model calls. */
+const ASK_TOOLS = [
+    'agentia_ai_ask',
+];
+/** Additive writes. */
+const CREATE_TOOLS = [
+    'agentia_credential_create',
+    'agentia_data_commit_create',
+    'agentia_data_filter_add',
+    'agentia_data_formula_create',
+    'agentia_data_template_convert_old',
+    'agentia_data_template_create',
+    'agentia_environment_create',
+    'agentia_pipeline_connection_create',
+    'agentia_pipeline_create',
+    'agentia_pipeline_stage_connection_create',
+    'agentia_project_create',
+    'agentia_repository_create',
+    'agentia_stage_create',
+    'agentia_testing_create',
+    'agentia_testing_data_table_create',
+    'agentia_testing_job_create',
+    'agentia_testing_job_download',
+    'agentia_testing_live_start',
+    'agentia_testing_project_create',
+    'agentia_testing_robot_create',
+    'agentia_testing_user_parameter_create',
+    'agentia_testing_variable_create',
+    'agentia_work_create',
+    'agentia_work_deployment_step_create',
+];
+/** Removes or resets state. */
+const DELETE_TOOLS = [
+    'agentia_data_filter_delete',
+    'agentia_data_template_delete',
+    'agentia_function_delete',
+    'agentia_pipeline_connection_delete',
+    'agentia_pipeline_stage_connection_delete',
+    'agentia_project_delete',
+    'agentia_repository_delete',
+    'agentia_repository_reset',
+    'agentia_stage_delete',
+    'agentia_testing_data_table_delete',
+    'agentia_testing_job_delete',
+    'agentia_testing_job_schedule_remove',
+    'agentia_testing_project_delete',
+    'agentia_testing_robot_delete',
+    'agentia_testing_user_parameter_delete',
+    'agentia_testing_variable_delete',
+    'agentia_work_delete',
+    'agentia_work_deployment_step_delete',
+];
+/** Read-only lookups. */
+const READ_TOOLS = [
+    'agentia_auth_get',
+    'agentia_credential_list',
+    'agentia_data_commit_list',
+    'agentia_data_dataset_file_content',
+    'agentia_data_dataset_file_list',
+    'agentia_data_filter_list',
+    'agentia_data_formula_list',
+    'agentia_data_records_match',
+    'agentia_data_records_search',
+    'agentia_data_sobject_fields',
+    'agentia_data_sobject_relationships',
+    'agentia_data_sync_preview_updates',
+    'agentia_data_template_get',
+    'agentia_data_template_get_detail',
+    'agentia_data_template_list',
+    'agentia_environment_auth_status',
+    'agentia_environment_get',
+    'agentia_environment_list',
+    'agentia_function_defaults',
+    'agentia_function_get',
+    'agentia_function_list',
+    'agentia_function_result_get',
+    'agentia_function_result_log_get',
+    'agentia_job_get',
+    'agentia_job_list',
+    'agentia_job_log_get',
+    'agentia_job_result_file_get',
+    'agentia_job_result_file_list',
+    'agentia_metadata_content_compare',
+    'agentia_metadata_content_get',
+    'agentia_metadata_dependency_list',
+    'agentia_metadata_index_compare',
+    'agentia_metadata_list',
+    'agentia_metadata_refresh_status',
+    'agentia_navigation_resolve',
+    'agentia_pipeline_connection_list',
+    'agentia_pipeline_get',
+    'agentia_pipeline_list',
+    'agentia_pipeline_stage_connection_list',
+    'agentia_project_default_get',
+    'agentia_project_get',
+    'agentia_project_list',
+    'agentia_promotion_conflict_get',
+    'agentia_promotion_conflict_list',
+    'agentia_promotion_get',
+    'agentia_promotion_list',
+    'agentia_repository_get',
+    'agentia_repository_list',
+    'agentia_repository_validate',
+    'agentia_stage_get',
+    'agentia_stage_list',
+    'agentia_testing_build_get',
+    'agentia_testing_build_latest',
+    'agentia_testing_build_list',
+    'agentia_testing_build_logs',
+    'agentia_testing_build_search',
+    'agentia_testing_data_table_get',
+    'agentia_testing_data_table_list',
+    'agentia_testing_job_files',
+    'agentia_testing_job_get',
+    'agentia_testing_job_list',
+    'agentia_testing_job_refs',
+    'agentia_testing_job_schedule_get',
+    'agentia_testing_live_history',
+    'agentia_testing_live_inspect',
+    'agentia_testing_live_reports',
+    'agentia_testing_live_screenshot',
+    'agentia_testing_live_status',
+    'agentia_testing_logs',
+    'agentia_testing_project_get',
+    'agentia_testing_project_list',
+    'agentia_testing_project_permission_get',
+    'agentia_testing_project_permission_list',
+    'agentia_testing_robot_get',
+    'agentia_testing_robot_list',
+    'agentia_testing_status',
+    'agentia_testing_user_parameter_get',
+    'agentia_testing_user_parameter_list',
+    'agentia_testing_variable_get',
+    'agentia_testing_variable_list',
+    'agentia_user_get',
+    'agentia_work_deployment_step_list',
+    'agentia_work_deployment_step_salesforce_flows',
+    'agentia_work_deployment_step_types',
+    'agentia_work_get',
+    'agentia_work_list',
+    'agentia_work_status',
+];
+/** Overwrites existing state. */
+const UPDATE_TOOLS = [
+    'agentia_auth_set',
+    'agentia_credential_update',
+    'agentia_data_filter_update',
+    'agentia_data_formula_update',
+    'agentia_data_template_save_detail',
+    'agentia_environment_update',
+    'agentia_function_upsert',
+    'agentia_pipeline_connection_update',
+    'agentia_pipeline_stage_connection_update',
+    'agentia_pipeline_update',
+    'agentia_project_default_set',
+    'agentia_project_default_unset',
+    'agentia_project_update',
+    'agentia_promotion_conflict_resolve',
+    'agentia_promotion_conflict_unresolve',
+    'agentia_promotion_job_step_update',
+    'agentia_repository_update',
+    'agentia_stage_update',
+    'agentia_testing_data_table_update',
+    'agentia_testing_job_schedule_set',
+    'agentia_testing_job_update',
+    'agentia_testing_job_upload',
+    'agentia_testing_live_set_options',
+    'agentia_testing_project_permission_set',
+    'agentia_testing_project_permission_update',
+    'agentia_testing_project_update',
+    'agentia_testing_robot_update',
+    'agentia_testing_update',
+    'agentia_testing_user_parameter_update',
+    'agentia_testing_variable_update',
+    'agentia_work_deployment_step_reorder',
+    'agentia_work_deployment_step_update',
+    'agentia_work_set',
+    'agentia_work_update',
+];
+/** Tools that only touch local state (keychain/config), not the gateway or Salesforce. */
+const LOCAL_ONLY_TOOLS = new Set([
+    'agentia_auth_get',
+    'agentia_project_default_get',
+    'agentia_project_default_set',
+    'agentia_project_default_unset',
+]);
+const TOOL_CLASSES = new Map([
+    ...ACTION_TOOLS.map((name) => [name, 'action']),
+    ...ASK_TOOLS.map((name) => [name, 'ask']),
+    ...CREATE_TOOLS.map((name) => [name, 'create']),
+    ...DELETE_TOOLS.map((name) => [name, 'delete']),
+    ...READ_TOOLS.map((name) => [name, 'read']),
+    ...UPDATE_TOOLS.map((name) => [name, 'update']),
+]);
+export function listClassifiedToolNames() {
+    return [...TOOL_CLASSES.keys()];
+}
+export function getToolAnnotations(toolName) {
+    const toolClass = TOOL_CLASSES.get(toolName);
+    if (toolClass === undefined)
+        return undefined;
+    return { ...CLASS_ANNOTATIONS[toolClass], openWorldHint: !LOCAL_ONLY_TOOLS.has(toolName) };
+}
+/** Returns the tool config with default annotations; annotations already set on the tool win. */
+export function withToolAnnotations(toolName, config) {
+    const defaults = getToolAnnotations(toolName);
+    if (defaults === undefined || typeof config !== 'object' || config === null)
+        return config;
+    const existing = config.annotations;
+    return { ...config, annotations: { ...defaults, ...existing } };
+}
+//# sourceMappingURL=tool-annotations.js.map

package/dist/lib/mcp/tools.js

@@ -47,6 +47,7 @@ import { workStatusEndpoint } from '../work-types.js';
 import { agentiaMcpAiToolHandlers, registerAgentiaMcpAiTools } from './ai-tools.js';
 import { agentiaMcpDataToolHandlers, registerAgentiaMcpDataTools } from './data-tools.js';
 import { agentiaMcpDeploymentStepToolHandlers, registerAgentiaMcpDeploymentStepTools } from './deployment-step-tools.js';
+import { agentiaMcpHealthCheckToolHandlers, registerAgentiaMcpHealthCheckTools } from './health-check-tools.js';
 import { safelyHandleTool, wrapMcpToolHandlers } from './result.js';
 import { agentiaMcpTestingToolHandlers, registerAgentiaMcpTestingTools } from './testing-tools.js';
 import { agentiaMcpWorkToolHandlers, registerAgentiaMcpWorkTools } from './work-tools.js';
@@ -1206,6 +1207,7 @@ export const agentiaMcpToolHandlers = wrapMcpToolHandlers({
     ...agentiaMcpAiToolHandlers,
     ...agentiaMcpDataToolHandlers,
     ...agentiaMcpDeploymentStepToolHandlers,
+    ...agentiaMcpHealthCheckToolHandlers,
     authGet,
     authSet,
     credentialCreate,
@@ -1366,6 +1368,7 @@ export function registerAgentiaMcpTools(server) {
     registerAgentiaMcpAiTools(server);
     registerAgentiaMcpDataTools(server);
     registerAgentiaMcpDeploymentStepTools(server);
+    registerAgentiaMcpHealthCheckTools(server);
     registerAgentiaMcpTestingTools(server);
     server.registerTool('agentia_environment_list', {
         description: 'List Copado environments via the CICD gateway.',

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

@@ -21,7 +21,8 @@ import { performWorkLocalCommit } from '../work-local-commit.js';
 import { reportLocalQualityGatesFailure, reportLocalQualityGatesOutcome, } from '../work-local-run-tests.js';
 import { capturingWorkPushHooks, performWorkPush, resolveActiveFeatureWorkItem, resolveWorkPushContext, resolveWorkPushNeed, } from '../work-push.js';
 import { performWorkSetNone } from '../work-set-none.js';
-import { isWorkSetWarning, parseWorkSetSelection, toWorkSetWarningResult } from '../work-set-selection.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';
 import { applySourceCredentialEnvironmentRule, featureBranchName, normalizeUserStoriesListPage, workCreateEndpoint, workDoneEndpoint, workEndpoint, workListEndpoint, workSetEndpoint, workSubmitEndpoint, } from '../work-types.js';
 import { safelyHandleTool } from './result.js';
@@ -213,6 +214,7 @@ async function workSet(args) {
         method: 'POST',
     });
     if (isWorkSetWarning(setResponse)) {
+        await writeWorkSetWarningSelection(setResponse);
         return toWorkSetWarningResult(setResponse);
     }
     const selection = parseWorkSetSelection(setResponse, args.baseBranch);
@@ -262,6 +264,12 @@ async function workPublish(args = {}) {
 async function workPush(args = {}) {
     return workPublish(args);
 }
+async function reportSubmitAheadBehindForMcp(workItem) {
+    return reportSubmitUserStoriesAheadBehind(workItem, {
+        log: (message) => capturingWorkPushHooks.log(message),
+        warn: (message) => capturingWorkPushHooks.log(`Warning: ${message}`),
+    });
+}
 async function promoteWorkItemDone(args = {}) {
     return withCapturedCommandOutput(async () => {
         const { branch, workItem } = await requireFeatureBranchWorkItem();
@@ -276,6 +284,7 @@ async function promoteWorkItemDone(args = {}) {
                 skipNestedMetadataDetection: args.skipNestedMetadataDetection,
             });
         }
+        const userStoriesAheadBehind = await reportSubmitAheadBehindForMcp(workItem);
         await waitForPendingCommitJobIfNeeded({
             hooks: capturingWorkPushHooks,
             workItem,
@@ -294,6 +303,7 @@ async function promoteWorkItemDone(args = {}) {
             done,
             push: pushResult,
             pushed: needsPush,
+            ...(userStoriesAheadBehind === undefined ? {} : { userStoriesAheadBehind }),
             workItem,
         };
     }, MCP_STDIO_CAPTURE_OPTIONS);
@@ -341,6 +351,7 @@ async function workSubmit(args = {}) {
                 skipNestedMetadataDetection: args.skipNestedMetadataDetection,
             });
         }
+        const userStoriesAheadBehind = await reportSubmitAheadBehindForMcp(workItem);
         await waitForPendingCommitJobIfNeeded({
             hooks: capturingWorkPushHooks,
             workItem,
@@ -359,6 +370,7 @@ async function workSubmit(args = {}) {
             pushed: needsPush,
             qualityGates,
             submit,
+            ...(userStoriesAheadBehind === undefined ? {} : { userStoriesAheadBehind }),
             workItem,
         };
     }, MCP_STDIO_CAPTURE_OPTIONS);
@@ -428,7 +440,7 @@ function providedCommitArgs(names, args) {
 async function workLocalCommit(args) {
     const cloudOnly = providedCommitArgs(CLOUD_ONLY_COMMIT_ARGS, args);
     if (cloudOnly.length > 0) {
-        throw new Error(`Local commit does not support ${cloudOnly.join(', ')}. Pass cloud: true to use POST /release/commit.`);
+        throw new Error(`Local commit does not support ${cloudOnly.join(', ')}. Use agentia_cloud_commit for POST /release/commit.`);
     }
     return performWorkLocalCommit({
         all: args.all === true,
@@ -469,17 +481,13 @@ function buildMcpWorkCommitInput(args) {
         recreateFeatureBranch: args.recreateFeatureBranch,
     };
 }
-async function workCommit(args = {}) {
-    // Local git commit is not exposed. Implementation remains in workLocalCommit.
-    if (args.cloud !== true) {
-        throw new Error('This tool creates Copado cloud metadata commits. For local Git work, use git commit then agentia_work_publish. Pass cloud: true for a Copado cloud commit. Permission and full-metadata selections belong on agentia_work_publish.');
-    }
+async function cloudCommit(args = {}) {
     if (args.local === true) {
-        throw new Error('local and cloud are mutually exclusive.');
+        throw new Error('This tool creates Copado cloud metadata commits. For local Git work, use git commit then agentia_work_publish.');
     }
     const localOnly = providedCommitArgs(LOCAL_ONLY_COMMIT_ARGS, args);
     if (localOnly.length > 0) {
-        throw new Error(`Cloud commit does not support ${localOnly.join(', ')}.`);
+        throw new Error(`Cloud commit does not support ${localOnly.join(', ')}. Use agentia_work_publish for ${localOnly.join(', ')}.`);
     }
     if (args.changes !== undefined && hasMcpSimpleCommitArgs(args)) {
         throw new Error('Use changes or simple metadata fields, not both.');
@@ -511,10 +519,11 @@ async function workCommit(args = {}) {
     });
 }
 export { workLocalCommit as retainedWorkLocalCommit };
-async function workPromote(args = {}) {
-    if (args.cloud !== true) {
-        throw new Error('Only cloud=true is supported for work promotion.');
-    }
+/** Compatibility alias of agentia_cloud_commit. Prefer agentia_cloud_commit. */
+async function workCommit(args = {}) {
+    return cloudCommit(args);
+}
+async function cloudPromote(args = {}) {
     if (args.recreatePromotionBranch === true && args.confirmRecreate !== true) {
         throw new Error('recreatePromotionBranch requires confirmRecreate=true.');
     }
@@ -550,13 +559,14 @@ async function workDone(args = {}) {
     });
 }
 export const agentiaMcpWorkToolHandlers = {
+    cloudCommit,
+    cloudPromote,
     workCommit,
     workCreate,
     workDelete,
     workDone,
     workGet,
     workList,
-    workPromote,
     workPublish,
     workPush,
     workSet,
@@ -645,7 +655,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, and leaves local work context unchanged. 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 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.',
         inputSchema: {
             baseBranch: z
                 .string()
@@ -680,79 +690,87 @@ export function registerAgentiaMcpWorkTools(server) {
         inputSchema: workPublishInputSchema,
         title: 'Agentia Work Push',
     }, (args) => safelyHandleTool(() => workPush(args || {})));
+    const cloudCommitInputSchema = {
+        action: z.enum(WORK_COMMIT_ACTIONS).optional().describe('Metadata action for simple input. Defaults to Add.'),
+        baseBranch: z.string().nullable().optional().describe('Optional base branch included in the commit request.'),
+        changes: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe(WORK_COMMIT_CHANGES_HELP),
+        commitId: z
+            .string()
+            .optional()
+            .describe('Existing local Git commit identifier to register when executeCommit is false.'),
+        dataTemplateSyncConfig: z
+            .array(z.unknown())
+            .optional()
+            .describe('Optional data-template synchronization configuration.'),
+        executeCommit: z.boolean().optional().describe('Execute the Copado commit job. Defaults to true.'),
+        id: z.string().optional().describe('User story Id. Defaults to the active work item from work set.'),
+        message: z
+            .string()
+            .optional()
+            .describe('Commit message. Required unless supplied in the request body.'),
+        metadataCategory: z.string().optional().describe(WORK_COMMIT_METADATA_CATEGORY_HELP),
+        metadataMessage: z.string().optional().describe('Optional per-change message for simple input.'),
+        metadataName: z.string().optional().describe('Metadata full name for simple input.'),
+        metadataRawJson: z.unknown().optional().describe('Optional raw metadata JSON value for simple input.'),
+        metadataType: z.string().optional().describe('Metadata type for simple input, for example ApexClass.'),
+        recreateFeatureBranch: z.boolean().optional().describe('Ask Copado to recreate the feature branch.'),
+        selection: z
+            .array(z.string())
+            .optional()
+            .describe('Selected files inside a bundle for SelectiveCommit simple input.'),
+        wait: z.boolean().optional().describe('Poll the commit job to a terminal status. Defaults to true.'),
+        waitTimeout: z.number().int().optional().describe('Maximum seconds to wait for the commit job. Defaults to 300.'),
+    };
+    const cloudPromoteInputSchema = {
+        confirmRecreate: z
+            .boolean()
+            .optional()
+            .describe('Required true when recreatePromotionBranch is true because MCP cannot prompt.'),
+        deploy: z.boolean().optional().describe('Use merge_and_deploy instead of promote-only merge.'),
+        deploymentStepIds: z
+            .array(z.string())
+            .optional()
+            .describe('Ordered deployment-step Salesforce IDs. Requires deploy=true.'),
+        id: z.string().optional().describe('User Story ID. Defaults to the active work item from work set.'),
+        ignoredMetadata: z.array(z.unknown()).optional().describe('Ignored metadata persisted before starting the run.'),
+        promotionId: z
+            .string()
+            .optional()
+            .describe('Explicit 18-character Promotion ID when the User Story belongs to multiple promotions.'),
+        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
+            .number()
+            .int()
+            .optional()
+            .describe(`Maximum total wait in seconds. Defaults to ${PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS}.`),
+    };
+    server.registerTool('agentia_cloud_commit', {
+        description: 'Create a Copado cloud metadata commit. Preflights the user story, submits POST /release/commit, and optionally waits for the job. Use simple metadata fields for one change or changes for multi-change requests. For Salesforce metadata, set metadataCategory to SFDX (or c: "SFDX" on each changes entry); Copado SFDX deploy skips entries that omit that field. For local Git work, use git commit then agentia_work_publish; pass permissions and fullMetadata on agentia_work_publish.',
+        inputSchema: cloudCommitInputSchema,
+        title: 'Agentia Cloud Commit',
+    }, (args) => safelyHandleTool(() => cloudCommit(args || {})));
     server.registerTool('agentia_work_commit', {
-        description: 'Create a Copado cloud metadata commit. Requires cloud: true. Preflights the user story, submits POST /release/commit, and optionally waits for the job. Use simple metadata fields for one change or changes for multi-change requests. For Salesforce metadata, set metadataCategory to SFDX (or c: "SFDX" on each changes entry); Copado SFDX deploy skips entries that omit that field. For local Git work, use git commit then agentia_work_publish; pass permissions and fullMetadata on agentia_work_publish.',
+        description: 'Compatibility alias of agentia_cloud_commit. Prefer agentia_cloud_commit. Create a Copado cloud metadata commit. cloud is ignored when present.',
         inputSchema: {
-            action: z.enum(WORK_COMMIT_ACTIONS).optional().describe('Metadata action for simple input. Defaults to Add.'),
-            baseBranch: z.string().nullable().optional().describe('Optional base branch included in the commit request.'),
-            changes: z
-                .array(z.record(z.string(), z.unknown()))
-                .optional()
-                .describe(WORK_COMMIT_CHANGES_HELP),
+            ...cloudCommitInputSchema,
             cloud: z
                 .boolean()
                 .optional()
-                .describe('Required. Create a Copado cloud metadata commit (POST /release/commit). Local Git commits use git commit then agentia_work_publish.'),
-            commitId: z
-                .string()
-                .optional()
-                .describe('Existing local Git commit identifier to register when executeCommit is false.'),
-            dataTemplateSyncConfig: z
-                .array(z.unknown())
-                .optional()
-                .describe('Optional data-template synchronization configuration.'),
-            executeCommit: z.boolean().optional().describe('Execute the Copado commit job. Defaults to true.'),
-            id: z.string().optional().describe('User story Id. Defaults to the active work item from work set.'),
-            message: z
-                .string()
-                .optional()
-                .describe('Commit message. Required unless supplied in the request body.'),
-            metadataCategory: z.string().optional().describe(WORK_COMMIT_METADATA_CATEGORY_HELP),
-            metadataMessage: z.string().optional().describe('Optional per-change message for simple input.'),
-            metadataName: z.string().optional().describe('Metadata full name for simple input.'),
-            metadataRawJson: z.unknown().optional().describe('Optional raw metadata JSON value for simple input.'),
-            metadataType: z.string().optional().describe('Metadata type for simple input, for example ApexClass.'),
-            recreateFeatureBranch: z.boolean().optional().describe('Ask Copado to recreate the feature branch.'),
-            selection: z
-                .array(z.string())
-                .optional()
-                .describe('Selected files inside a bundle for SelectiveCommit simple input.'),
-            wait: z.boolean().optional().describe('Poll the commit job to a terminal status. Defaults to true.'),
-            waitTimeout: z.number().int().optional().describe('Maximum seconds to wait for the commit job. Defaults to 300.'),
+                .describe('Ignored. This tool is a compatibility alias of agentia_cloud_commit.'),
         },
         title: 'Agentia Work Commit',
     }, (args) => safelyHandleTool(() => workCommit(args || {})));
-    server.registerTool('agentia_work_promote', {
+    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.',
-        inputSchema: {
-            cloud: z.boolean().optional().describe('Must be true. Uses the cloud promotion run endpoint.'),
-            confirmRecreate: z
-                .boolean()
-                .optional()
-                .describe('Required true when recreatePromotionBranch is true because MCP cannot prompt.'),
-            deploy: z.boolean().optional().describe('Use merge_and_deploy instead of promote-only merge.'),
-            deploymentStepIds: z
-                .array(z.string())
-                .optional()
-                .describe('Ordered deployment-step Salesforce IDs. Requires deploy=true.'),
-            id: z.string().optional().describe('User Story ID. Defaults to the active work item from work set.'),
-            ignoredMetadata: z.array(z.unknown()).optional().describe('Ignored metadata persisted before starting the run.'),
-            promotionId: z
-                .string()
-                .optional()
-                .describe('Explicit 18-character Promotion ID when the User Story belongs to multiple promotions.'),
-            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
-                .number()
-                .int()
-                .optional()
-                .describe(`Maximum total wait in seconds. Defaults to ${PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS}.`),
-        },
-        title: 'Agentia Work Promote',
-    }, (args) => safelyHandleTool(() => workPromote(args || {})));
+        inputSchema: cloudPromoteInputSchema,
+        title: 'Agentia Cloud Promote',
+    }, (args) => safelyHandleTool(() => cloudPromote(args || {})));
     server.registerTool('agentia_work_submit', {
-        description: 'Submit the current feature/US-XXXX work item for pipeline quality gates and validation. Runs project-root .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows) when present, then fetches origin/<lastBaseBranch> and counts origin/<lastBaseBranch>..HEAD before checking origin. Pushes and registers commits when that feature-only range is non-empty and the branch is ahead of origin. When the last pending related job template name contains Commit, waits up to 5 minutes for that job before calling headless work/submit. With done=true or deploy=true, matches Copado UI Submit when promoting (headless work/done) and uses the same commit wait. Prefer this over agentia_work_done.',
+        description: 'Submit the current feature/US-XXXX work item for pipeline quality gates and validation. Runs project-root .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows) when present, then fetches origin/<lastBaseBranch> and counts origin/<lastBaseBranch>..HEAD before checking origin. Pushes and registers commits when that feature-only range is non-empty and the branch is ahead of origin. When the last pending related job template name contains Commit, waits up to 5 minutes for that job before calling headless work/submit. Before submit or promote, counts user stories ahead and behind between the source environment and the next pipeline environment, and warns when stories behind might cause promotion conflicts. With done=true or deploy=true, matches Copado UI Submit when promoting (headless work/done) and uses the same commit wait. Prefer this over agentia_work_done.',
         inputSchema: {
             apexTestClasses: z
                 .string()

package/dist/lib/metadata-pathspecs.js

@@ -0,0 +1,4 @@
+import {modules} from './runtime.js';
+const DEFAULT_SFDX_METADATA_ROOT = modules["metadata-pathspecs.js"]["DEFAULT_SFDX_METADATA_ROOT"]
+const guessMetadataPathspecs = modules["metadata-pathspecs.js"]["guessMetadataPathspecs"]
+export {DEFAULT_SFDX_METADATA_ROOT, guessMetadataPathspecs};