Explain Agent Merge behavior in chat

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: benibenj

src/vs/platform/agentHost/common/agentMerge.ts

@@ -306,8 +306,122 @@ export const agentMergeDisableReasons = {
 } as const;
 
 /** The transcript notice shown once Agent Merge starts watching a branch. */
-export function agentMergeEnabledNotice(branchName: string): string {
-	return localize('agentMerge.notice.enabled', "Agent Merge is on and watching {0}.", appendEscapedMarkdownInlineCode(branchName));
+export function agentMergeEnabledNotice(target: Pick<AgentMergeTarget, 'branchName' | 'pullRequestUrl'>, configuration: AgentMergeConfiguration): string {
+	const lines = [
+		target.pullRequestUrl
+			? localize('agentMerge.notice.enabled.withPullRequest', "Agent Merge is on for {0} and is monitoring its pull request.", appendEscapedMarkdownInlineCode(target.branchName))
+			: localize('agentMerge.notice.enabled', "Agent Merge is on for {0}. It will wait for a pull request on this branch, then monitor it.", appendEscapedMarkdownInlineCode(target.branchName)),
+	];
+	if (configuration.addressReviews) {
+		lines.push(localize('agentMerge.notice.enabled.addressReviews', "It will ask the agent to address new pull request review comments."));
+	}
+	if (configuration.fixCI) {
+		lines.push(localize('agentMerge.notice.enabled.fixCI', "It will ask the agent to fix failing CI checks."));
+	}
+	if (configuration.resolveConflicts) {
+		lines.push(localize('agentMerge.notice.enabled.resolveConflicts', "It will ask the agent to resolve merge conflicts and update the branch when it falls behind."));
+	}
+	if (!configuration.addressReviews && !configuration.fixCI && !configuration.resolveConflicts) {
+		lines.push(localize('agentMerge.notice.enabled.noRepairs', "It will monitor the pull request but will not ask the agent to repair blockers."));
+	}
+	if (configuration.addressReviews) {
+		lines.push(configuration.replyAttribution
+			? localize('agentMerge.notice.enabled.replyAttribution', "Replies it posts will identify Agent Merge as the source.")
+			: localize('agentMerge.notice.enabled.noReplyAttribution', "Replies it posts will not identify Agent Merge as the source."));
+	}
+	lines.push(
+		configuration.addressReviews
+			? localize('agentMerge.notice.enabled.waiting', "After each update, it will wait for new CI results and review comments.")
+			: localize('agentMerge.notice.enabled.waitingForCI', "After each update, it will wait for new CI results."),
+		agentMergeMergeBehaviorNotice(configuration.mergePullRequest),
+	);
+	if (configuration.mergePullRequest !== 'never') {
+		lines.push(agentMergeMergeMethodNotice(configuration.mergeMethod));
+	}
+	return lines.join(' ');
+}
+
+/** The transcript notice shown when effective Agent Merge behavior changes. */
+export function agentMergeConfigurationChangedNotice(previous: AgentMergeConfiguration, current: AgentMergeConfiguration): string | undefined {
+	const changes: string[] = [];
+	if (previous.addressReviews !== current.addressReviews) {
+		changes.push(current.addressReviews
+			? localize('agentMerge.notice.configuration.addressReviews.enabled', "It will now address new pull request review comments.")
+			: localize('agentMerge.notice.configuration.addressReviews.disabled', "It will no longer address new pull request review comments or wait for them before merging."));
+	}
+	if (previous.fixCI !== current.fixCI) {
+		changes.push(current.fixCI
+			? localize('agentMerge.notice.configuration.fixCI.enabled', "It will now fix failing CI checks.")
+			: localize('agentMerge.notice.configuration.fixCI.disabled', "It will no longer fix failing CI checks."));
+	}
+	if (previous.resolveConflicts !== current.resolveConflicts) {
+		changes.push(current.resolveConflicts
+			? localize('agentMerge.notice.configuration.resolveConflicts.enabled', "It will now resolve merge conflicts and update the branch when it falls behind.")
+			: localize('agentMerge.notice.configuration.resolveConflicts.disabled', "It will no longer resolve merge conflicts or update a behind branch."));
+	}
+	if (previous.mergePullRequest !== current.mergePullRequest) {
+		changes.push(agentMergeMergeBehaviorChangedNotice(current.mergePullRequest));
+	}
+	if (current.mergePullRequest !== 'never'
+		&& (previous.mergeMethod !== current.mergeMethod || previous.mergePullRequest === 'never')) {
+		changes.push(agentMergeMergeMethodChangedNotice(current.mergeMethod));
+	}
+	if (previous.replyAttribution !== current.replyAttribution && current.addressReviews) {
+		changes.push(current.replyAttribution
+			? localize('agentMerge.notice.configuration.replyAttribution.enabled', "Replies it posts will now identify Agent Merge as the source.")
+			: localize('agentMerge.notice.configuration.replyAttribution.disabled', "Replies it posts will no longer identify Agent Merge as the source."));
+	}
+	return changes.length > 0
+		? [localize('agentMerge.notice.configuration.changed', "Agent Merge settings changed."), ...changes].join(' ')
+		: undefined;
+}
+
+function agentMergeMergeBehaviorNotice(mergePullRequest: AgentMergeMergePullRequest): string {
+	switch (mergePullRequest) {
+		case 'always':
+			return localize('agentMerge.notice.merge.always', "When the pull request is ready, Agent Merge will merge it automatically.");
+		case 'ifUnchanged':
+			return localize('agentMerge.notice.merge.ifUnchanged', "When the pull request is ready, Agent Merge will merge it automatically only if it has not made changes.");
+		case 'never':
+			return localize('agentMerge.notice.merge.never', "It will not merge the pull request automatically and will keep monitoring it.");
+	}
+}
+
+function agentMergeMergeMethodChangedNotice(mergeMethod: AgentMergeMethod): string {
+	switch (mergeMethod) {
+		case 'auto':
+			return localize('agentMerge.notice.configuration.mergeMethod.auto', "It will now choose an available merge method automatically.");
+		case 'squash':
+			return localize('agentMerge.notice.configuration.mergeMethod.squash', "It will now squash-merge the pull request.");
+		case 'merge':
+			return localize('agentMerge.notice.configuration.mergeMethod.merge', "It will now create a merge commit.");
+		case 'rebase':
+			return localize('agentMerge.notice.configuration.mergeMethod.rebase', "It will now rebase and merge the pull request.");
+	}
+}
+
+function agentMergeMergeMethodNotice(mergeMethod: AgentMergeMethod): string {
+	switch (mergeMethod) {
+		case 'auto':
+			return localize('agentMerge.notice.mergeMethod.auto', "It will choose an available merge method automatically.");
+		case 'squash':
+			return localize('agentMerge.notice.mergeMethod.squash', "It will squash-merge the pull request.");
+		case 'merge':
+			return localize('agentMerge.notice.mergeMethod.merge', "It will create a merge commit.");
+		case 'rebase':
+			return localize('agentMerge.notice.mergeMethod.rebase', "It will rebase and merge the pull request.");
+	}
+}
+
+function agentMergeMergeBehaviorChangedNotice(mergePullRequest: AgentMergeMergePullRequest): string {
+	switch (mergePullRequest) {
+		case 'always':
+			return localize('agentMerge.notice.configuration.merge.always', "It will now merge the pull request automatically when it is ready.");
+		case 'ifUnchanged':
+			return localize('agentMerge.notice.configuration.merge.ifUnchanged', "It will now merge the pull request when it is ready, but only if Agent Merge has not made changes.");
+		case 'never':
+			return localize('agentMerge.notice.configuration.merge.never', "It will no longer merge the pull request automatically.");
+	}
 }
 
 /** The transcript notice shown when the user, rather than the controller, turns Agent Merge off. */

src/vs/platform/agentHost/common/meta/agentSystemNotificationMeta.ts

@@ -7,6 +7,8 @@ export const enum AgentSystemNotificationKind {
 	WorktreeCreationFailure = 'worktreeCreationFailure',
 	/** Agent Merge started monitoring the session's branch. */
 	AgentMergeEnabled = 'agentMergeEnabled',
+	/** Effective Agent Merge behavior changed while monitoring. */
+	AgentMergeConfigurationChanged = 'agentMergeConfigurationChanged',
 	/** Agent Merge stopped monitoring the session, usually on its own. */
 	AgentMergeDisabled = 'agentMergeDisabled',
 }
@@ -18,6 +20,7 @@ export const enum AgentSystemNotificationSeverity {
 const knownKinds: ReadonlySet<string> = new Set<string>([
 	AgentSystemNotificationKind.WorktreeCreationFailure,
 	AgentSystemNotificationKind.AgentMergeEnabled,
+	AgentSystemNotificationKind.AgentMergeConfigurationChanged,
 	AgentSystemNotificationKind.AgentMergeDisabled,
 ]);
 

src/vs/platform/agentHost/node/agentMergeController.ts

@@ -15,7 +15,7 @@ import { IGitHubService } from '../../github/common/githubService.js';
 import { PullRequestRef, PullRequestSnapshot, PullRequestSubscription } from '../../github/common/githubPullRequestService.js';
 import { GitHubRequestError } from '../../github/common/githubTransport.js';
 import { ILogService } from '../../log/common/log.js';
-import { AgentMergeConfigKey, AgentMergeConfiguration, AgentMergeDisableReason, AgentMergeSessionState, AgentMergeTarget, AGENT_MERGE_UNKNOWN_COMMIT, agentMergeDisableReasons, agentMergeDisabledNotice, agentMergeEnabledNotice, agentMergeGateFragments, agentMergeMergePullRequestDemotedNotice, agentMergeRootConfigSchema, defaultAgentMergeConfiguration, evaluateAgentMerge, readAgentMergeSessionState, resolveAgentMergeConfiguration, resolveMergeMethod, shouldStopMergingAfterAgentChanges } from '../common/agentMerge.js';
+import { AgentMergeConfigKey, AgentMergeConfiguration, AgentMergeDisableReason, AgentMergeSessionState, AgentMergeTarget, AGENT_MERGE_UNKNOWN_COMMIT, agentMergeConfigurationChangedNotice, agentMergeDisableReasons, agentMergeDisabledNotice, agentMergeEnabledNotice, agentMergeGateFragments, agentMergeMergePullRequestDemotedNotice, agentMergeRootConfigSchema, defaultAgentMergeConfiguration, evaluateAgentMerge, readAgentMergeSessionState, resolveAgentMergeConfiguration, resolveMergeMethod, shouldStopMergingAfterAgentChanges } from '../common/agentMerge.js';
 import { buildAgentMergePrompt } from '../common/agentMergePrompt.js';
 import { IAgentHostGitStateService } from '../common/agentHostGitStateService.js';
 import { IAgentHostGitService } from '../common/agentHostGitService.js';
@@ -103,6 +103,7 @@ export class AgentMergeController extends Disposable {
 	 * sync that {@link _disable} triggers cannot post a second, reasonless one.
 	 */
 	private readonly _monitoredSessions = new Set<string>();
+	private readonly _announcedConfigurations = new Map<string, AgentMergeConfiguration>();
 
 	constructor(
 		private readonly _options: IAgentMergeControllerOptions,
@@ -123,6 +124,11 @@ export class AgentMergeController extends Disposable {
 				return;
 			}
 			const session = event.session.toString();
+			if (!previous?.enabled && current?.enabled && current.target) {
+				this._postEnabledNotice(session, current);
+			} else {
+				this._postConfigurationChangedNotice(session, current);
+			}
 			if (this._resetRepairBaselineOnReselection(session, previous, current)) {
 				// The reset re-enters this listener, which then syncs.
 				return;
@@ -137,6 +143,7 @@ export class AgentMergeController extends Disposable {
 		}));
 		this._register(this._stateManager.onDidRemoveSession(session => {
 			this._monitoredSessions.delete(session);
+			this._announcedConfigurations.delete(session);
 			this._stopRuntime(session);
 		}));
 		this._register(this._gitStateService.onDidRefreshSessionGitState(session => {
@@ -147,6 +154,8 @@ export class AgentMergeController extends Disposable {
 		this._register(this._gitStateService.onDidChangeSessionGitHubState(session => this._schedule(session, 0)));
 		this._register(this._configurationService.onDidRootConfigChange(() => {
 			for (const session of this._stateManager.getSessionUris()) {
+				const agentMerge = readAgentMergeSessionState(this._stateManager.getSessionState(session)?.config?.values);
+				this._postConfigurationChangedNotice(session, agentMerge);
 				this._syncSession(session);
 			}
 		}));
@@ -251,6 +260,7 @@ export class AgentMergeController extends Disposable {
 			if (this._monitoredSessions.delete(session) && state) {
 				this._postNotice(session, AgentSystemNotificationKind.AgentMergeDisabled, agentMergeDisabledNotice());
 			}
+			this._announcedConfigurations.delete(session);
 			if (agentMerge?.injectedConfiguration) {
 				this._restoreInjectedConfiguration(session, agentMerge);
 			}
@@ -289,6 +299,14 @@ export class AgentMergeController extends Disposable {
 			this._runtimes.set(session, runtime);
 			this._monitoredSessions.add(session);
 			this._logService.info(`[AgentMergeController] Started session runtime: session=${session}, hasTarget=${agentMerge.target !== undefined}, overrides=${formatOverrideKeys(agentMerge)}`);
+			if (agentMerge.target) {
+				const announced = this._announcedConfigurations.get(session);
+				if (announced) {
+					this._postConfigurationChangedNotice(session, agentMerge);
+				} else {
+					this._announcedConfigurations.set(session, this._getConfiguration(agentMerge));
+				}
+			}
 		}
 		this._schedule(session, 0);
 	}
@@ -406,7 +424,7 @@ export class AgentMergeController extends Disposable {
 			this._logService.info(`[AgentMergeController] Captured session branch and feedback watermark: session=${session}`);
 			// Announce only on the first capture: a resumed session already has a
 			// target, so restarting the host must not repeat the notice.
-			this._postNotice(session, AgentSystemNotificationKind.AgentMergeEnabled, agentMergeEnabledNotice(branchName));
+			this._postEnabledNotice(session, { ...agentMerge, target });
 			this._updateAgentMergeState(session, agentMerge, { target });
 			return;
 		}
@@ -661,15 +679,50 @@ export class AgentMergeController extends Disposable {
 	}
 
 	private _getConfiguration(agentMerge: AgentMergeSessionState): AgentMergeConfiguration {
-		const defaults: AgentMergeConfiguration = {
+		return resolveAgentMergeConfiguration(this._getRootConfiguration(), agentMerge.overrides);
+	}
+
+	private _getRootConfiguration(): AgentMergeConfiguration {
+		return {
 			addressReviews: this._configurationService.getRootValue(agentMergeRootConfigSchema, AgentMergeConfigKey.AddressReviews) ?? defaultAgentMergeConfiguration.addressReviews,
 			fixCI: this._configurationService.getRootValue(agentMergeRootConfigSchema, AgentMergeConfigKey.FixCI) ?? defaultAgentMergeConfiguration.fixCI,
 			resolveConflicts: this._configurationService.getRootValue(agentMergeRootConfigSchema, AgentMergeConfigKey.ResolveConflicts) ?? defaultAgentMergeConfiguration.resolveConflicts,
 			mergePullRequest: this._configurationService.getRootValue(agentMergeRootConfigSchema, AgentMergeConfigKey.MergePullRequest) ?? defaultAgentMergeConfiguration.mergePullRequest,
 			mergeMethod: this._configurationService.getRootValue(agentMergeRootConfigSchema, AgentMergeConfigKey.MergeMethod) ?? defaultAgentMergeConfiguration.mergeMethod,
 			replyAttribution: this._configurationService.getRootValue(agentMergeRootConfigSchema, AgentMergeConfigKey.ReplyAttribution) ?? defaultAgentMergeConfiguration.replyAttribution,
 		};
-		return resolveAgentMergeConfiguration(defaults, agentMerge.overrides);
+	}
+
+	private _postEnabledNotice(session: string, agentMerge: AgentMergeSessionState): void {
+		if (!agentMerge.enabled
+			|| !agentMerge.target
+			|| !this._isFeatureEnabled()
+			|| this._stateManager.getSessionState(session)?.lifecycle !== SessionLifecycle.Ready) {
+			return;
+		}
+		const configuration = this._getConfiguration(agentMerge);
+		this._announcedConfigurations.set(session, configuration);
+		this._postNotice(session, AgentSystemNotificationKind.AgentMergeEnabled, agentMergeEnabledNotice(agentMerge.target, configuration));
+	}
+
+	private _postConfigurationChangedNotice(session: string, current: AgentMergeSessionState | undefined): void {
+		if (!current?.enabled
+			|| !current.target
+			|| !this._isFeatureEnabled()
+			|| !this._runtimes.has(session)) {
+			return;
+		}
+		const previousConfiguration = this._announcedConfigurations.get(session);
+		const currentConfiguration = this._getConfiguration(current);
+		if (!previousConfiguration) {
+			this._announcedConfigurations.set(session, currentConfiguration);
+			return;
+		}
+		const notice = agentMergeConfigurationChangedNotice(previousConfiguration, currentConfiguration);
+		this._announcedConfigurations.set(session, currentConfiguration);
+		if (notice) {
+			this._postNotice(session, AgentSystemNotificationKind.AgentMergeConfigurationChanged, notice);
+		}
 	}
 
 	private _canRepairFork(snapshot: PullRequestSnapshot): boolean {
@@ -843,10 +896,12 @@ export class AgentMergeController extends Disposable {
 		}
 		this._logService.info(`[AgentMergeController] Turning automatic merge off because a repair turn changed the worktree: session=${session}, repairBaseCommit=${agentMerge.repairBaseCommit}, currentCommit=${currentCommit ?? 'unresolved'}`);
 		this._postNotice(session, AgentSystemNotificationKind.AgentMergeDisabled, agentMergeMergePullRequestDemotedNotice());
+		const overrides = { ...agentMerge.overrides, mergePullRequest: 'never' } as const;
+		this._announcedConfigurations.set(session, this._getConfiguration({ ...agentMerge, overrides }));
 		this._configurationService.updateSessionConfig(session, {
 			[SessionConfigKey.AgentMerge]: {
 				enabled: agentMerge.enabled,
-				overrides: { ...agentMerge.overrides, mergePullRequest: 'never' },
+				overrides,
 			},
 			// Dropping the baseline is what makes re-selecting the option start
 			// fresh: without it the next evaluation would demote again against
@@ -897,6 +952,7 @@ export class AgentMergeController extends Disposable {
 		// Claim the transition before the config write re-enters `_doSyncSession`,
 		// so the reasoned notice below is the only one the user sees.
 		this._monitoredSessions.delete(session);
+		this._announcedConfigurations.delete(session);
 		this._postNotice(session, AgentSystemNotificationKind.AgentMergeDisabled, reason.notice);
 		const patch: Record<string, unknown> = {
 			[SessionConfigKey.AgentMerge]: {