microsoft/vscode/agent-host-chat-contributions

Agent Host Chat Contributions

Use the contribution model for a self-contained behavior that crosses an agent-host chat lifecycle boundary. Read these files before changing the model:

• src/vs/platform/agentHost/common/agentHostChatContributionsService.ts
• src/vs/platform/agentHost/node/agentHostChatContributionsService.ts
• src/vs/platform/agentHost/node/chatContributions/TODO.md
• src/vs/platform/agentHost/node/chatContributions/builtInChatContributions.ts

The rule that prevents the old failure mode

New cross-cutting features go in contributions, not in `AgentSideEffects` or `AgentService`.

AgentSideEffects has shed well over 700 lines by extracting seventeen behaviors. Do not put another lifecycle side effect, outgoing-prompt addition, restored-turn enrichment, admission check, or action observer back into either large orchestration class. AgentSideEffects dispatches the lifecycle and retains routing and send mechanics; AgentService owns session lifecycle and invokes hydration and memento eviction. See agentSideEffects.ts and agentService.ts.

This is also a review rule: code added to either file needs a specific reason that it is routing, a correctness invariant, provider-shaped behavior, or a dispatcher call site. "It was convenient to add here" is not a reason.

Decide before you code

Write a contribution when the behavior answers yes to this test:

1. Does it react to a lifecycle moment the hooks already name — a turn request asking to proceed, a completed turn, a dispatched action, a turn about to be sent, a restored turn list, or a chat being restored?
2. Can an explicitly registered, dependency-injected unit own it without changing protocol routing or provider mapping?
3. Does it compose with other behavior in a defined order?

Examples are admission gating, local-command interception, checkpoint and changeset work, queue draining, GitHub-reference attachment, title handling, persisted usage, session input-needed aggregation, session flag persistence, chat drafts, a chat's own config, worktree announcements, unread state, rich-link guidance, and chat-surface guidance. Their directories under node/chatContributions/ are the reference implementations.

Do not use a contribution for the following:

• Subagent signal routing and buffering in node/agentSideEffects.ts are routing fabric and correctness invariants.
• Turn-id remapping in node/agentSideEffects.ts is also routing fabric.
• The three SDK event mappers and three attachment serializers are provider-shaped.
• Provider-shaped overlays applied during restore, such as seeding a draft's model from IAgent-supplied session metadata in _doRestoreSession. Moving one would push provider metadata into IHydrationContext for one consumer.

If the answer is "this must route every signal correctly before state changes" or "this differs by SDK," it is not a contribution. Open work and standing caveats are tracked in node/chatContributions/TODO.md.

Keep the hook surface small

IAgentHostChatContribution has seven hooks in common/agentHostChatContributionsService.ts. Only add another method when no existing payload can express the behavior.

The set was once reduced from six to four:

• onTurnConsumable became onTurnEnd with TurnEndReason.kind === 'localCommand'.
• onUserMessage became onOutgoingTurn.

Prefer adding a discriminant or payload to an existing type, such as a new TurnEndReason variant, over adding a hook. A proposed single-purpose hook with one caller and one implementer is the smell that produced both removals. Do not create an abstraction merely to move one direct call.

The three hooks added since clear a specific bar: no existing payload could express them because they fire at a different moment or from a different source, not merely with different data.

• onHydrateChat restores host-owned chat state before a chat enters the catalog. onHydrateTurns runs lazily, after a provider returns turns, so reusing it would leave a restored peer chat untitled until it was opened.
• onIncomingRequest gates a turn before it reaches a provider, and can reject it. No observer hook can refuse.
• onDidDispatchAction observes server-dispatched and rejected actions, which onDidApplyClientAction structurally cannot see.

Adding a { kind: ... } discriminant to an existing hook was considered and rejected for onHydrateChat: the discriminant guidance covers payload variants within one moment, the way TurnEndReason discriminates outcomes of a single turn ending.

Anatomy and registration

Give every contribution its own directory under node/chatContributions/<feature>/. It owns its implementation, helpers, and tests as it grows. A contribution must have:

• static readonly id, unique across registrations.
• An explicit order, even when it currently appears independent.
• A constructor whose first parameter is IAgentHostChatContributionContext, followed by injected services.
• A single registration in node/chatContributions/builtInChatContributions.ts.

This is the complete shape of the existing Markdown plan rich-link contribution, adapted from markdownPlanRichLinks/markdownPlanRichLinksContribution.ts:

export class MarkdownPlanRichLinksContribution extends Disposable implements IAgentHostChatContribution {
	static readonly id = 'markdownPlanRichLinks';
	readonly order = 100;
	constructor(
		protected readonly _context: IAgentHostChatContributionContext,
		@IAgentConfigurationService private readonly _agentConfigService: IAgentConfigurationService,
	) {
		super();
	}
	onOutgoingTurn(turn: IOutgoingTurn): ISendContribution | undefined {
		return this._agentConfigService.getRootValue(platformRootSchema, AgentHostMarkdownPlanRichLinksEnabledConfigKey)
			? { instructions: [createMarkdownPlanRichLinksInstruction(turn.chat)] }
			: undefined;
	}
}

Add its constructor to the one built-in list with contributions.registerContribution(MarkdownPlanRichLinksContribution). That list is activated by activateAgentHostContributions in node/agentHostContributions.ts; do not add a competing registration site. The dispatcher constructs each contribution through IInstantiationService, rejects duplicate ids, and disposes it on unregistration.

The seven hooks

The call sites are in node/agentSideEffects.ts, node/agentHostTurnStarter.ts, and node/agentService.ts.

Ordering is behavior

order is load-bearing. The dispatcher sorts lower values first; registration order breaks ties only. Ordering is per hook, so the 100-series can be reused for hydration independently of outgoing turns. See node/agentHostChatContributionsService.ts.

Use explicit orders to preserve a required sequence:

• LocalCommandContribution is 50 and TurnAdmissionContribution is 100 on onIncomingRequest. That order is load-bearing: local commands were always intercepted before the read-only guard, so /rename still works in a read-only or archived chat.
• CheckpointAndChangesetContribution runs at 100 so it captures a checkpoint before later changeset-related work.
• QueueDrainContribution is 200 and SessionInputNeededContribution is 200.
• GitHubReferencesContribution and ChatSurfaceContribution are 300 where applicable.
• SessionTitleContribution is 400, MarkUnreadContribution and SideChatContribution are 500, ChatDraftContribution is 600, ChatConfigContribution is 650, and SessionFlagsContribution is 700.

markUnread and sideChat both declare 500 and both implement onTurnEnd, so their relative sequence rests on registration order. Give a new contribution a distinct order rather than joining that tie.

A silent reordering regression already happened. The built-in-sequence regression tests in test/node/chatContributions.test.ts protect the original turn-end, outgoing-turn, and hydration sequences. Add or update those tests when ordering changes intentionally.

Depend on services, not a growing context

Never add callbacks or services to IAgentHostChatContributionContext. It is only contribution identity plus centrally evicted mementos. Coordinate through @Injectable services.

IAgentHostChatContributionHost is intentionally the narrow bridge to AgentSideEffects: it has only hostLaunchKind and sendTurnMessage. It grew to seven members before being cut back to two by promoting collaborators to real services:

• IAgentHostSessionTitleController
• IAgentHostProviderService
• IAgentHostTelemetryReporter
• IAgentHostTurnTracker
• IAgentHostToolCallTracker
• IAgentHostLocalCommands

IAgentHostWorktreeIsolation is injectable too. "It isn't injectable" was a wrong conclusion caused by service-registration order and later disproved. Trace registration from node/agentHostServices.ts through node/agentHostBootstrap.ts and createAgentServiceComposition in node/agentServiceComposition.ts. Register a real service before the instantiation path constructs contributions; do not smuggle it through the context or host bridge.