Let agent host sessions tolerate hosts that differ from the client

[Osvaldo Ortega (osortega)]

Three ways a session against a host that is older than, or shaped differently from, the client would fail outright. All three surfaced against a remote host running an older copilotd, but none of the fixes are specific to it — AgentHostSessionHandler serves local, SSH and tunnel sessions too.

1. Customization shape skew

Customizations moved from an enabled boolean to list-shaped enablement in protocol 0.8.0. A host below that version expects the superseded shape and rejects the whole request with invalid params: missing field "enabled", failing createSession and leaving no session at all.

Client-published customizations are now dropped for such a host, degrading to a session without them — which is what that host would have made of them anyway; the alternative is no session.

The gate is applied on both paths that publish an active client. Reconciliation republishes it after creation, so gating only createSession leaves the second path broken.

Worth noting for reviewers: the version registry has exhaustive, compile-enforced maps for actions and notifications, but nothing for field-level shape changes like this one, so the version constant here is hand-maintained.

2. Working directories the host cannot address

A workspace may be the repository itself (https://github.com/owner/repo) while the agent runs against a checkout on the host’s own disk. Sending the remote URI fails createSession with unsupported scheme "https"; expected "file".

Directories the host cannot address are now dropped, falling back to undefined so it chooses its own. The host’s reported defaultDirectory names the scheme it can address, so this adapts per host rather than hardcoding file. Hosts that report no default are left alone.

3. "Couldn’t open session" for a session that does not exist yet

A provider can legitimately address a session id before the host knows it, with createSession bringing it into being. Subscribing first fails with NotFound, which rendered a failure banner that the very next step resolved.

The banner is suppressed for NotFound specifically — a genuine open failure still renders, which a test covers directly so the suppression cannot quietly widen.

Risk

All three are no-ops for a current host with matching schemes: the version gate passes, every directory is addressable, and sessions resolve. The blast radius is wider than the case that motivated them, so the no-op paths are the ones worth checking.

Validation

• npm run typecheck-client
• ./scripts/test.sh --glob "**/agentHostChatContribution.test.js" — 328 passing, including 6 new tests covering both sides of each fix (drops and keeps, suppresses and still renders).

Note on the NotFound suppression

The suppression is deliberately broad: it covers every AHP NotFound, not only a session the client minted and expects to create on first send.

This costs a notice, not a capability. A session the host does not know is unreadable either way and is recreated on the next send in both cases, so the only difference is that "Couldn't open session" no longer appears. Cloud sandbox sessions are unaffected entirely, since Mission Control mirrors their history at /events and a dormant environment opens read-only from that rather than reaching this path.

The remaining case — a persisted local/SSH/tunnel session the host has lost — is also short-lived, because _refreshSessions evicts any cached session the host does not list. Narrowing the suppression would need a positive provider-level signal that the client minted the id; not worth the API surface for a missing notice in that window.

[Copilot]

Pull request overview

Improves Agent Host compatibility with older or differently shaped hosts.

Changes:

• Gates customization payloads by protocol version.
• Filters unsupported working-directory schemes.
• Suppresses expected pre-creation NotFound errors and adds tests.

Show a summary per file

File	Description
agentHostSessionHandler.ts	Adds compatibility handling for customizations, directories, and missing sessions.
agentHostChatContribution.test.ts	Adds compatibility regression tests.
sessionProtocol.ts	Exposes the generic AHP NotFound code.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Suppressed comments (1)

src/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostSessionHandler.ts:5605

• computeWorkingDirectories guarantees that index 0 is the primary directory. In a mixed-scheme multi-root workspace, filtering can remove that primary while retaining a later entry, silently promoting the secondary to the host's working directory instead of letting the host choose its default. Preserve the primary-first invariant: if the primary is not addressable, return undefined; only filter secondary entries when the primary remains.

		return addressable.length > 0 ? addressable : undefined;

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Balanced