@copado/agentia-cli 0.56.0-alpha.0 → 0.57.0-alpha.0

package/dist/commands/cicd/promotion/run.d.ts

@@ -0,0 +1,23 @@
+import { AgentiaCommand } from '../../../lib/agentia-command.js';
+import { type PromotionRunResult } from '../../../lib/promotion-run.js';
+export default class PromotionRun extends AgentiaCommand {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'deployment-step-id': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'ignored-metadata-json': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        operation: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'recreate-promotion-branch': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        resume: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'wait-timeout': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<PromotionRunResult>;
+    protected toErrorJson(err: unknown): unknown;
+    private execute;
+    private hooks;
+}

package/dist/commands/cicd/promotion/run.js

@@ -0,0 +1,137 @@
+import { confirm } from '@inquirer/prompts';
+import { Args, Flags } from '@oclif/core';
+import { AgentiaCommand } from '../../../lib/agentia-command.js';
+import { formatPromotionRunResult, isPromotionRunExecutionError, parseIgnoredMetadataJson, performPromotionResume, performPromotionRun, PROMOTION_OPERATIONS, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, promotionRunErrorJson, PromotionRunValidationError, } from '../../../lib/promotion-run.js';
+export default class PromotionRun extends AgentiaCommand {
+    static args = {
+        id: Args.string({
+            description: '18-character Salesforce Promotion ID',
+            required: true,
+        }),
+    };
+    static description = [
+        'Preflight, start, and optionally wait for a Copado promotion execution.',
+        'Use --resume to continue an existing failed or conflict-resolved execution without starting a duplicate promotion.',
+    ].join(' ');
+    static examples = [
+        '<%= config.bin %> <%= command.id %> a0BXXXXXXXXXXXXXXX --operation merge',
+        '<%= config.bin %> <%= command.id %> a0BXXXXXXXXXXXXXXX --operation merge_and_deploy --json',
+        '<%= config.bin %> <%= command.id %> a0BXXXXXXXXXXXXXXX --resume a4NXXXXXXXXXXXXXXX',
+    ];
+    static flags = {
+        'deployment-step-id': Flags.string({
+            description: 'Ordered deployment-step Salesforce ID. Can be provided multiple times.',
+            multiple: true,
+        }),
+        'ignored-metadata-json': Flags.string({
+            description: 'JSON array to persist through ignored-metadata before starting the promotion.',
+        }),
+        operation: Flags.string({
+            description: 'Promotion operation. Required unless --resume is used.',
+            options: [...PROMOTION_OPERATIONS],
+        }),
+        'recreate-promotion-branch': Flags.boolean({
+            description: 'Recreate the promotion branch before execution. Requires confirmation or --yes.',
+        }),
+        resume: Flags.string({
+            description: 'Resume this existing JobExecution ID instead of calling the promotion run endpoint.',
+        }),
+        wait: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Poll promotion and deployment executions to terminal status.',
+        }),
+        'wait-timeout': Flags.integer({
+            default: PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS,
+            description: 'Maximum total seconds to wait for promotion and deployment executions.',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            default: false,
+            description: 'Confirm promotion branch recreation without prompting.',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(PromotionRun);
+        const runFlags = flags;
+        if (!Number.isInteger(runFlags['wait-timeout']) || runFlags['wait-timeout'] <= 0) {
+            this.error('--wait-timeout must be a positive integer.', { exit: 2 });
+        }
+        if (runFlags.resume !== undefined && runFlags.operation !== undefined) {
+            this.error('Use --resume or --operation, not both.', { exit: 2 });
+        }
+        if (runFlags.resume === undefined && runFlags.operation === undefined) {
+            this.error('--operation is required unless --resume is used.', { exit: 2 });
+        }
+        if (runFlags.resume !== undefined) {
+            if (runFlags['deployment-step-id'] !== undefined ||
+                runFlags['ignored-metadata-json'] !== undefined ||
+                runFlags['recreate-promotion-branch'] === true) {
+                this.error('--resume cannot be combined with run request flags.', { exit: 2 });
+            }
+            return this.execute(() => performPromotionResume({
+                hooks: this.hooks(),
+                jobExecutionId: runFlags.resume,
+                promotionId: args.id,
+                timeoutSeconds: runFlags['wait-timeout'],
+                wait: runFlags.wait,
+            }));
+        }
+        if (runFlags['recreate-promotion-branch'] === true && !runFlags.yes) {
+            if (this.jsonEnabled() || !process.stdin.isTTY) {
+                this.error('Promotion branch recreation requires confirmation. Pass --yes for headless or JSON execution.', {
+                    exit: 2,
+                });
+            }
+            const confirmed = await confirm({
+                default: false,
+                message: `Recreate the promotion branch for ${args.id}? Existing promotion branch changes may be replaced.`,
+            });
+            if (!confirmed) {
+                this.error('Promotion canceled.', { exit: 1 });
+            }
+        }
+        return this.execute(() => performPromotionRun({
+            deploymentStepIds: runFlags['deployment-step-id'],
+            hooks: this.hooks(),
+            ignoredMetadata: parseIgnoredMetadataJson(runFlags['ignored-metadata-json']),
+            operation: runFlags.operation,
+            promotionId: args.id,
+            recreatePromotionBranch: runFlags['recreate-promotion-branch'],
+            timeoutSeconds: runFlags['wait-timeout'],
+            wait: runFlags.wait,
+        }));
+    }
+    toErrorJson(err) {
+        const base = super.toErrorJson(err);
+        return promotionRunErrorJson(base, err);
+    }
+    async execute(action) {
+        try {
+            const result = await action();
+            this.display(() => this.log(formatPromotionRunResult(result)));
+            return result;
+        }
+        catch (error) {
+            if (error instanceof PromotionRunValidationError) {
+                this.error(error.message, { exit: 2 });
+            }
+            if (isPromotionRunExecutionError(error)) {
+                this.display(() => {
+                    if (error.result !== undefined) {
+                        this.log(formatPromotionRunResult(error.result));
+                    }
+                });
+                error.oclif = { exit: 1 };
+            }
+            throw error;
+        }
+    }
+    hooks() {
+        return {
+            log: (message) => this.display(() => this.log(message)),
+            withSpinner: (message, action) => this.withSpinner(message, action),
+        };
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/cicd/promotion/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../../src/commands/cicd/promotion/run.ts"],"names":[],"mappings":"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"}

package/dist/commands/cicd/work/promote.d.ts

@@ -0,0 +1,25 @@
+import { AgentiaCommand } from '../../../lib/agentia-command.js';
+import { type PromotionRunResult } from '../../../lib/promotion-run.js';
+export type WorkPromoteResult = PromotionRunResult & {
+    workItemId: string;
+};
+export default class WorkPromote extends AgentiaCommand {
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        cloud: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        deploy: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'deployment-step-id': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'ignored-metadata-json': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'promotion-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'recreate-promotion-branch': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'wait-timeout': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<WorkPromoteResult>;
+    protected toErrorJson(err: unknown): unknown;
+}

package/dist/commands/cicd/work/promote.js

@@ -0,0 +1,141 @@
+import { confirm } from '@inquirer/prompts';
+import { Args, Flags } from '@oclif/core';
+import { AgentiaCommand } from '../../../lib/agentia-command.js';
+import { formatPromotionRunResult, isPromotionRunExecutionError, parseIgnoredMetadataJson, performPromotionRun, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, promotionRunErrorJson, PromotionRunValidationError, resolvePromotionIdForWorkItem, } from '../../../lib/promotion-run.js';
+import { resolveWorkItemId, WorkActiveResolutionError } from '../../../lib/work-active.js';
+export default class WorkPromote extends AgentiaCommand {
+    static args = {
+        id: Args.string({
+            description: 'User Story ID (defaults to the active work item from `work set`)',
+            required: false,
+        }),
+    };
+    static description = [
+        'Promote the explicit or active User Story through its Copado Promotion.',
+        'Requires --cloud and selects promote-only unless --deploy is passed.',
+    ].join(' ');
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --cloud',
+        '<%= config.bin %> <%= command.id %> a07XXXXXXXXXXXXXXX --cloud --promotion-id a0BXXXXXXXXXXXXXXX',
+        '<%= config.bin %> <%= command.id %> --cloud --deploy --json',
+    ];
+    static flags = {
+        cloud: Flags.boolean({
+            default: false,
+            description: 'Use the Copado cloud promotion API. Required for this command.',
+        }),
+        deploy: Flags.boolean({
+            default: false,
+            description: 'Use merge_and_deploy instead of promote-only merge.',
+        }),
+        'deployment-step-id': Flags.string({
+            description: 'Ordered deployment-step Salesforce ID. Can be provided multiple times with --deploy.',
+            multiple: true,
+        }),
+        'ignored-metadata-json': Flags.string({
+            description: 'JSON array to persist through ignored-metadata before starting the promotion.',
+        }),
+        'promotion-id': Flags.string({
+            description: 'Explicit 18-character Promotion ID when the User Story belongs to multiple promotions.',
+        }),
+        'recreate-promotion-branch': Flags.boolean({
+            description: 'Recreate the promotion branch before execution. Requires confirmation or --yes.',
+        }),
+        wait: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Poll promotion and deployment executions to terminal status.',
+        }),
+        'wait-timeout': Flags.integer({
+            default: PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS,
+            description: 'Maximum total seconds to wait for promotion and deployment executions.',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            default: false,
+            description: 'Confirm promotion branch recreation without prompting.',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkPromote);
+        const promoteFlags = flags;
+        if (!promoteFlags.cloud) {
+            this.error('Only cloud promotion is supported for this command. Pass --cloud.', { exit: 2 });
+        }
+        if (!Number.isInteger(promoteFlags['wait-timeout']) || promoteFlags['wait-timeout'] <= 0) {
+            this.error('--wait-timeout must be a positive integer.', { exit: 2 });
+        }
+        if (!promoteFlags.deploy && promoteFlags['deployment-step-id'] !== undefined) {
+            this.error('--deployment-step-id requires --deploy.', { exit: 2 });
+        }
+        let workItemId;
+        try {
+            workItemId = await resolveWorkItemId(args.id);
+        }
+        catch (error) {
+            if (error instanceof WorkActiveResolutionError) {
+                this.error(error.message, {
+                    exit: 1,
+                    suggestions: [`${this.config.bin} cicd work set <id>`],
+                });
+            }
+            throw error;
+        }
+        try {
+            const promotionId = await this.withSpinner('Resolving User Story promotion', () => resolvePromotionIdForWorkItem(workItemId, promoteFlags['promotion-id']));
+            if (promoteFlags['recreate-promotion-branch'] === true && !promoteFlags.yes) {
+                if (this.jsonEnabled() || !process.stdin.isTTY) {
+                    this.error('Promotion branch recreation requires confirmation. Pass --yes for headless or JSON execution.', {
+                        exit: 2,
+                    });
+                }
+                const confirmed = await confirm({
+                    default: false,
+                    message: `Recreate the promotion branch for ${promotionId}? Existing promotion branch changes may be replaced.`,
+                });
+                if (!confirmed) {
+                    this.error('Promotion canceled.', { exit: 1 });
+                }
+            }
+            const result = await performPromotionRun({
+                deploymentStepIds: promoteFlags['deployment-step-id'],
+                hooks: {
+                    log: (message) => this.display(() => this.log(message)),
+                    withSpinner: (message, action) => this.withSpinner(message, action),
+                },
+                ignoredMetadata: parseIgnoredMetadataJson(promoteFlags['ignored-metadata-json']),
+                operation: promoteFlags.deploy ? 'merge_and_deploy' : 'merge',
+                promotionId,
+                recreatePromotionBranch: promoteFlags['recreate-promotion-branch'],
+                timeoutSeconds: promoteFlags['wait-timeout'],
+                wait: promoteFlags.wait,
+            });
+            const workResult = { ...result, workItemId };
+            this.display(() => {
+                this.log(`User Story: ${workItemId}`);
+                this.log(formatPromotionRunResult(result));
+            });
+            return workResult;
+        }
+        catch (error) {
+            if (error instanceof PromotionRunValidationError) {
+                this.error(error.message, { exit: 2 });
+            }
+            if (isPromotionRunExecutionError(error)) {
+                this.display(() => {
+                    if (error.result !== undefined) {
+                        this.log(`User Story: ${workItemId}`);
+                        this.log(formatPromotionRunResult(error.result));
+                    }
+                });
+                error.oclif = { exit: 1 };
+            }
+            throw error;
+        }
+    }
+    toErrorJson(err) {
+        const base = super.toErrorJson(err);
+        return promotionRunErrorJson(base, err);
+    }
+}
+//# sourceMappingURL=promote.js.map

package/dist/commands/cicd/work/promote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote.js","sourceRoot":"","sources":["../../../../src/commands/cicd/work/promote.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp/tools.d.ts

@@ -10,6 +10,7 @@ import { type PipelineConnection, type PipelineDescribe, type PipelineListFilter
 import { type ProjectDefaultScope } from '../project-defaults.js';
 import { type Project, type ProjectListFilters } from '../project-types.js';
 import { type PromotionConflict, type PromotionConflictMode, type PromotionConflictResolutionResult, type PromotionConflictUndoResult } from '../promotion-conflicts.js';
+import { type PromotionOperation } from '../promotion-run.js';
 import { type PromotionDetail, type PromotionListFilters } from '../promotion-types.js';
 import { type GitRepository, type RepositoryValidateResult } from '../repository-types.js';
 import { type User } from '../user-types.js';
@@ -178,12 +179,26 @@ declare function environmentGet(args: {
     environment: Environment;
 }>;
 type PromotionListArgs = PromotionListFilters;
+type PromotionRunArgs = {
+    confirmRecreate?: boolean;
+    deploymentStepIds?: string[];
+    ignoredMetadata?: unknown[];
+    operation?: PromotionOperation;
+    promotionId: string;
+    recreatePromotionBranch?: boolean;
+    resumeJobExecutionId?: string;
+    wait?: boolean;
+    waitTimeout?: number;
+};
 declare function promotionList(args?: PromotionListArgs): Promise<Record<string, unknown>>;
 declare function promotionGet(args: {
     id: string;
 }): Promise<{
     promotion: PromotionDetail;
 }>;
+declare function promotionRun(args: PromotionRunArgs): Promise<{
+    result: import("../promotion-run.js").PromotionRunResult;
+}>;
 declare function environmentCreate(args: EnvironmentCreateArgs): Promise<{
     environment: Environment;
 }>;
@@ -475,6 +490,33 @@ export declare const agentiaMcpToolHandlers: {
         assignedToMe?: boolean;
         ownedByMe?: boolean;
     }) => Promise<Record<string, unknown>>;
+    workPromote: (args?: {
+        cloud?: boolean;
+        confirmRecreate?: boolean;
+        deploy?: boolean;
+        deploymentStepIds?: string[];
+        id?: string;
+        ignoredMetadata?: unknown[];
+        promotionId?: string;
+        recreatePromotionBranch?: boolean;
+        wait?: boolean;
+        waitTimeout?: number;
+    }) => Promise<{
+        workItemId: string;
+        context: Record<string, unknown>;
+        deploymentSteps: import("../promotion-run.js").PromotionDeploymentStep[];
+        ignoredMetadata?: unknown[];
+        jobMonitors: import("../promotion-run.js").PromotionJobMonitor[];
+        mode: "resume" | "run";
+        operation?: PromotionOperation;
+        promotionAfter?: PromotionDetail;
+        promotionBefore: PromotionDetail;
+        promotionId: string;
+        request?: import("../promotion-run.js").PromotionRunRequest;
+        resultId: string;
+        run: import("../promotion-run.js").PromotionRunResponse;
+        wait: boolean;
+    }>;
     workPush: () => Promise<import("../work-types.js").WorkPushResult>;
     workSet: (args: {
         baseBranch?: string;
@@ -996,6 +1038,7 @@ export declare const agentiaMcpToolHandlers: {
     promotionConflictUnresolve: typeof promotionConflictUnresolve;
     promotionGet: typeof promotionGet;
     promotionList: typeof promotionList;
+    promotionRun: typeof promotionRun;
     repositoryCreate: typeof repositoryCreate;
     repositoryDelete: typeof repositoryDelete;
     repositoryGet: typeof repositoryGet;

package/dist/lib/mcp/tools.js

@@ -27,6 +27,7 @@ import { buildSetValues, collectSelectedKeys } from '../project-default-flags.js
 import { PROJECT_DEFAULT_KEYS } from '../project-defaults.js';
 import { normalizeProject, normalizeProjectsListPage, projectEndpoint, projectsListEndpoint, } from '../project-types.js';
 import { buildPromotionConflictResolutionRequest, normalizePromotionConflicts, PROMOTION_CONFLICT_MODES, promotionConflictContentEndpoint, promotionConflictResolveEndpoint, promotionConflictsEndpoint, promotionConflictUndoEndpoint, withPromotionConflictErrorTranslation, } from '../promotion-conflicts.js';
+import { performPromotionResume, performPromotionRun, PROMOTION_OPERATIONS, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, } from '../promotion-run.js';
 import { normalizePromotionDetail, normalizePromotionsListPage, promotionEndpoint, promotionListEndpoint, } from '../promotion-types.js';
 import { REPOSITORY_STRING_VALIDATION_KEYS, validateNonEmptyStringFields as validateRepositoryNonEmptyStringFields, } from '../repository-flags.js';
 import { normalizeRepositoriesListPage, normalizeRepository, normalizeRepositoryValidateResult, repositoriesEndpoint, REPOSITORY_AUTH_TYPES, REPOSITORY_PROVIDERS, REPOSITORY_SOURCE_FORMATS, repositoryEndpoint, repositoryResetEndpoint, repositoryValidateEndpoint, withRequiredRepositoryFields, } from '../repository-types.js';
@@ -52,6 +53,10 @@ async function environmentGet(args) {
     });
     return { environment };
 }
+const silentPromotionRunHooks = {
+    log() { },
+    withSpinner: async (_message, action) => action(),
+};
 async function promotionList(args = {}) {
     const response = await CicdGateway.call({
         endpoint: promotionListEndpoint(args),
@@ -66,6 +71,45 @@ async function promotionGet(args) {
     });
     return { promotion: normalizePromotionDetail(response) };
 }
+async function promotionRun(args) {
+    const waitTimeout = args.waitTimeout ?? PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS;
+    if (!Number.isInteger(waitTimeout) || waitTimeout <= 0) {
+        throw new Error('waitTimeout must be a positive integer.');
+    }
+    if (args.recreatePromotionBranch === true && args.confirmRecreate !== true) {
+        throw new Error('recreatePromotionBranch requires confirmRecreate=true.');
+    }
+    if (args.resumeJobExecutionId !== undefined) {
+        if (args.operation !== undefined ||
+            args.deploymentStepIds !== undefined ||
+            args.ignoredMetadata !== undefined ||
+            args.recreatePromotionBranch !== undefined) {
+            throw new Error('resumeJobExecutionId cannot be combined with run request fields.');
+        }
+        const result = await performPromotionResume({
+            hooks: silentPromotionRunHooks,
+            jobExecutionId: args.resumeJobExecutionId,
+            promotionId: args.promotionId,
+            timeoutSeconds: waitTimeout,
+            wait: args.wait ?? true,
+        });
+        return { result };
+    }
+    if (args.operation === undefined) {
+        throw new Error('operation is required unless resumeJobExecutionId is provided.');
+    }
+    const result = await performPromotionRun({
+        deploymentStepIds: args.deploymentStepIds,
+        hooks: silentPromotionRunHooks,
+        ignoredMetadata: args.ignoredMetadata,
+        operation: args.operation,
+        promotionId: args.promotionId,
+        recreatePromotionBranch: args.recreatePromotionBranch,
+        timeoutSeconds: waitTimeout,
+        wait: args.wait ?? true,
+    });
+    return { result };
+}
 async function environmentCreate(args) {
     const payload = buildCreatePayload(args.name, {
         'apex-test-level': args.apexTestLevel,
@@ -776,6 +820,7 @@ export const agentiaMcpToolHandlers = {
     promotionConflictUnresolve,
     promotionGet,
     promotionList,
+    promotionRun,
     repositoryCreate,
     repositoryDelete,
     repositoryGet,
@@ -912,6 +957,34 @@ export function registerAgentiaMcpTools(server) {
         },
         title: 'Agentia Promotion Get',
     }, (args) => safelyHandleTool(() => promotionGet(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: {
+            confirmRecreate: z
+                .boolean()
+                .optional()
+                .describe('Required true when recreatePromotionBranch is true because MCP cannot prompt.'),
+            deploymentStepIds: z
+                .array(z.string())
+                .optional()
+                .describe('Ordered deployment-step Salesforce IDs. The gateway order is used when omitted.'),
+            ignoredMetadata: z.array(z.unknown()).optional().describe('Ignored metadata persisted before starting the run.'),
+            operation: z
+                .enum(PROMOTION_OPERATIONS)
+                .optional()
+                .describe('Promotion operation. Required unless resumeJobExecutionId is supplied.'),
+            promotionId: z.string().describe('18-character Salesforce Promotion ID.'),
+            recreatePromotionBranch: z.boolean().optional().describe('Recreate the promotion branch before execution.'),
+            resumeJobExecutionId: z.string().optional().describe('Resume this existing promotion execution instead of /run.'),
+            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 Promotion Run',
+    }, (args) => safelyHandleTool(() => promotionRun(args)));
     server.registerTool('agentia_job_list', {
         description: 'List Copado job executions via the CICD gateway.',
         inputSchema: {