feat: reorganize AHP around channels (RFC #117)#127
Merged
Conversation
Generalizes AHP's subscription mechanism into a uniform "channel" model.
Every URI-addressable resource — root, sessions, terminals, and future
stateless streams like logs or LSP/MCP relays — is now a channel. Push
messages (subscribe results, action envelopes, protocol notifications,
client dispatches) all carry a top-level `channel: URI` so routing is
uniform across types.
Highlights:
- Channels can be state-bearing (root/session/terminal) or stateless
(snapshot omitted), opening the door to non-state pubsub channels
without further wire churn.
- Action envelopes own the channel; individual action payloads no
longer carry their own `session` / `terminal` URIs.
- Protocol notifications are top-level methods (`root/sessionAdded`,
`root/sessionRemoved`, `root/sessionSummaryChanged`, `auth/required`)
instead of a `notification` wrapper.
- Root URI renames to `ahp-root://`; session URIs use the
`ahp-session:` scheme with provider on `SessionSummary.provider`.
This is breaking on the wire. The protocol is still 0.1.0 (draft), so
the changes were folded in rather than bumping the version. A new
migration skill at `plugins/channels-migration-plugin/` walks an agent
through upgrading a pre-channels consumer end to end — start there if
you have client/server code to migrate.
The spec has been restructured around channels (new Root/Session/
Terminal channel pages; `lifecycle.md` is now connection-level only),
and the guide has been refreshed to match. Type-level tests in
`types/version/message-checks.ts` assert that every notification's
params extend `{ channel: URI }`.
Reducer fixtures, JSON Schemas, and the Swift/Rust generated clients
were regenerated. 196/196 tests pass with full reducer coverage.
Closes #117
roblourens
previously approved these changes
May 15, 2026
Brings changesets, session/customizationUpdated, and the multi-host Rust & Swift SDKs from main onto the channels branch. Removes v1.ts/v2.ts version snapshots (no longer relevant on this branch). Aligns the Rust and Swift multi-host SDKs with the channel-based wire model (channel on envelopes and dispatch params, top-level root/* and auth/required notifications, no session/terminal fields on action payloads, optional snapshot on SubscribeResult).
benvillalobos
approved these changes
May 18, 2026
dmitrivMS
approved these changes
May 18, 2026
connor4312
added a commit
to microsoft/vscode
that referenced
this pull request
May 19, 2026
* agentHost: adopt channel-based AHP wire model Adopts the channel-based Agent Host Protocol revision from microsoft/agent-host-protocol#127. Subscriptions, action delivery, and protocol notifications now all route over named channels identified by a top-level `channel: URI` field, replacing the pre-channels subscribe / dispatch / notify model. - Renames `ROOT_STATE_URI` from `agenthost:/root` to `ahp-root://` and adds an `isAhpRootChannel` helper that tolerates both the canonical wire form and the workbench `URI` round-tripped form (`ahp-root:`). - Threads a `channel` parameter through every action dispatch path: `IAgentService.dispatchAction`, `IAgentConnection.dispatch`, `AgentHostStateManager.dispatchServerAction` / `dispatchClientAction`, and `AgentSubscriptionManager.dispatchOptimistic`. Individual action payloads no longer carry `session` / `terminal` / `changeset` fields; the envelope carries the channel. - Replaces the `{ method: 'notification', params: { notification } }` wrapper with top-level JSON-RPC methods (`root/sessionAdded`, `root/sessionRemoved`, `root/sessionSummaryChanged`, `auth/required`). Each notification's params now carry their own `channel: URI` field. - Renames the per-command identifying field to `channel` for the channel- scoped commands (`createSession`, `disposeSession`, `createTerminal`, `disposeTerminal`, `fetchTurns`, `completions`, `invokeChangesetOperation`). Connection-level commands hard-code the root channel string. - Updates the subscribe result to `{ snapshot? }` and the `SubscribeParams` / `UnsubscribeParams` field name from `resource` to `channel`. - Drops the removed `ProtocolNotification`, `NotificationType`, `NotificationMethodParams`, and `NotificationMap` exports; provides a thin compat `NotificationType` constant keyed by method name for consumers that still discriminate notification variants. - Adapts `AgentSubscription` routing to switch on `envelope.channel` rather than inspecting per-action URI fields (`_isRelevantEnvelope` replaces `_isRelevantAction`). - Migrates all producers (`agentService`, `agentSideEffects`, `agentConfigurationService`, `agentHostChangesetService`, `agentHostTerminalManager`, `agentHostStateManager`, `protocolServerHandler`, Claude/Copilot agent sessions, terminal manager, etc.) and consumers (workbench session handler, terminal contribution, pty, customization harness, provider tests) to the new shapes. (Commit message generated by Copilot) * agentHost: address Copilot review for channels migration Addresses feedback from Copilot's review of #317251: - Update real-SDK integration test helpers and protocol integration tests to use the channel-based command shapes (rename `session` / `resource` to `channel`, add `channel: 'ahp-root://'` to connection-level commands, drop `session` from action payloads, route via params-level `channel`). - Treat the canonical `ahp-root://` and the URI-normalized `ahp-root:` forms as equivalent in `_isRelevantToClient` so root broadcasts reach a client that subscribed using either form (mirrors `isAhpRootChannel` already in use elsewhere). - Drop a `..` hop from the `NotificationType` import path in the local and remote session-provider tests; import from `state/sessionActions.js` directly. - Drop a stale post-merge `session: SESSION_STR` in `claudeMapSessionEvents.test.ts:Test 9.5` and the matching `requestResourceAccess` test expectation in `agentHostFileSystemProvider.test.ts` so they match the new channel-based shapes (root cause of the macOS browser CI failure). (Commit message generated by Copilot) * tests * import
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generalizes AHP's subscription mechanism into a uniform "channel" model. Every URI-addressable resource — root, sessions, terminals, and future stateless streams like logs or LSP/MCP relays — is now a channel. Push messages (subscribe results, action envelopes, protocol notifications, client dispatches) all carry a top-level
channel: URIso routing is uniform across types.Highlights:
session/terminalURIs.root/sessionAdded,root/sessionRemoved,root/sessionSummaryChanged,auth/required) instead of anotificationwrapper.ahp-root://; session URIs use theahp-session:scheme with provider onSessionSummary.provider.The spec has been restructured around channels (new Root/Session/ Terminal channel pages;
lifecycle.mdis now connection-level only), and the guide has been refreshed to match. Type-level tests intypes/version/message-checks.tsassert that every notification's params extend{ channel: URI }.Reducer fixtures, JSON Schemas, and the Swift/Rust generated clients were regenerated. 196/196 tests pass with full reducer coverage.
Closes #117