Add Canvas channel (spec + all clients)

[colbylwilliams]

Implements the Canvas surface proposed in #297. A Canvas is a host-driven, interactive UI surface (editor, browser, terminal, document view, …) that a session can open and drive over AHP. This PR adds the full protocol surface in the canonical types/ tree, wires it through the four per-language generators, and hand-ports the runtime pieces to all five client mirrors.

What's included

• Capability — a canvas client capability advertising which native canvas types the client can render.
• Discovery — canvasProviders published atomically on SessionActiveClient (same lifecycle as tools), plus CanvasAvailability / CanvasProviderSource in session state.
• Per-instance channels — one ahp-canvas:/<id> channel per open canvas instance (mirrors the terminal / changeset pattern), carrying canvas/updated, canvas/closeRequested, and the opaque canvas/message bridge.
• Provider methods — server→client canvasProviderOpen / canvasProviderInvokeAction / canvasProviderClose in ServerCommandMap, mirrored in CommandMap (the resource* precedent).
• In-band content — canvasReadResource + the opaque canvas/message path.
• Error — CanvasProviderError carrying { code, message }.
• Version — no PROTOCOL_VERSION bump. The canvas actions register at the current spec version (0.5.1) in ACTION_INTRODUCED_IN, and the CHANGELOG bullets land under ## [Unreleased]. Per repo convention (and the session/inputNeeded precedent), bumping PROTOCOL_VERSION and rotating the ## [X.Y.Z] heading is a separate release-time chore, not part of a feature PR. Client package versions stay 0.5.0 (bumped at release time).

Cross-language surface

• Types authored in types/ (errors, capability, channels-canvas/, channels-session/ state + actions + reducer, common actions enum/union, messages maps, version registry, index).
• Generators wired through find-protocol-sources, generate-action-origin, and generate-{go,rust,kotlin,swift}; generate-markdown gets the canvas slug + channel section.
• Clients — reducer hand-ports for Rust, Kotlin, Swift, and Go, plus the TS reducer, all exercised by the shared conformance fixtures.

Fixtures

Reducer fixtures cover: provider-registry replace, open-catalogue replace, canvas/updated sparse merge (present overwrites / absent preserves), canvas/closeRequested no-op, and canvas/message no-op.

Validated deviations from the proposal

1. canvas/updated uses a value-based sparse merge (present field overwrites, absent preserves) rather than the proposal's three-state null-clears / absent-preserves model. The three-state model isn't portable: the conformance harness collapses JSON null → undefined, and the generated Rust/Kotlin/Swift/Go nullable fields can't distinguish null from absent after deserialization. Action fields are therefore title?: string (no | null), and fresh snapshots on (re)subscribe cover the reset case.
2. No "unknown-instance no-op" fixture: the channel is per-instance (the envelope's channel scopes it), so canvas/updated carries no instanceId and the reducer has no instance-lookup branch.
3. CanvasProviderSource is modeled as a named discriminated union (CanvasProviderKind enum + CanvasServerProviderSource / CanvasClientProviderSource) rather than an inline anonymous union, because the per-language generators need named variants and the editorial rules mandate a *Kind discriminant.
4. canvas/message is bidirectional; since the action-origin model is binary it's marked @clientDispatchable (clients may send; the server may also emit). The reducer handles it via the full CanvasAction union regardless.

[Copilot]

Pull request overview

Adds the new Canvas protocol surface (capability + discovery + per-instance channel + provider request family) to the canonical types/ tree, then propagates it through schema/docs generation and the Rust/Go/Swift/Kotlin/TypeScript client mirrors, alongside a protocol version bump to 0.6.0.

Changes:

• Introduces Canvas state, actions, commands, errors, and session discovery fields in types/ (plus reducers + fixtures).
• Updates generators and regenerated artifacts (client generated types, JSON schemas, action-origin tables, version registries).
• Adds/updates specification and guide documentation, release metadata, and per-artifact CHANGELOG entries.

Show a summary per file

File	Description
types/version/registry.ts	Bumps protocol version + registers canvas action introduction versions.
types/version/message-checks.ts	Updates compile-time command map expectations for canvas methods.
types/test-cases/reducers/232-session-canvaseschanged-sets-registry.json	Adds session reducer fixture for canvases registry replacement.
types/test-cases/reducers/233-session-opencanvaseschanged-sets-catalogue.json	Adds session reducer fixture for open canvases catalogue replacement.
types/test-cases/reducers/234-canvas-updated-merges-all-fields.json	Adds canvas reducer fixture for full sparse-merge update.
types/test-cases/reducers/235-canvas-updated-partial-preserves-absent.json	Adds canvas reducer fixture for partial merge (preserve absent).
types/test-cases/reducers/236-canvas-updated-partial-complementary.json	Adds canvas reducer fixture for complementary partial merge.
types/test-cases/reducers/237-canvas-closerequested-no-op.json	Adds canvas reducer fixture ensuring closeRequested is a no-op.
types/test-cases/reducers/238-canvas-message-no-op.json	Adds canvas reducer fixture ensuring message is a no-op.
types/test-cases/reducers/239-canvas-unknown-action-type-is-no-op.json	Adds fixture for unknown canvas action type no-op behavior.
types/state.ts	Exports canvas channel state from the state barrel.
types/reducers.ts	Exports the new canvas reducer from reducer barrel.
types/reducers.test.ts	Wires canvas reducer into fixture runner + source scanning.
types/messages.test.ts	Adds canvas channel sources to message tests’ scan set.
types/index.ts	Re-exports canvas types/actions/commands/reducer from public API.
types/common/state.ts	Extends snapshot state union to include CanvasState.
types/common/messages.ts	Registers canvas commands in CommandMap + ServerCommandMap.
types/common/errors.ts	Adds CanvasProviderError code and data payload type.
types/common/commands.ts	Adds ClientCapabilities.canvas capability definition.
types/common/actions.ts	Adds canvas/session canvas action types into common action unions.
types/commands.ts	Exports canvas channel commands from the commands barrel.
types/channels-session/state.ts	Adds canvases/openCanvases fields and canvas discovery types.
types/channels-session/reducer.ts	Adds session reducer handling for canvases/openCanvases actions.
types/channels-session/actions.ts	Defines session/canvasesChanged and session/openCanvasesChanged.
types/channels-canvas/state.ts	Defines CanvasState for per-instance ahp-canvas: channels.
types/channels-canvas/reducer.ts	Implements sparse-merge reducer and no-op signal handling.
types/channels-canvas/commands.ts	Defines canvas provider family + canvasReadResource content request.
types/channels-canvas/actions.ts	Defines canvas channel actions + dispatchability annotations.
types/actions.ts	Exports canvas channel actions from the actions barrel.
types/action-origin.generated.ts	Adds canvas action unions and dispatchability map entries.
scripts/generate-swift.ts	Updates Swift generator for canvas types/unions/commands/actions/errors.
scripts/generate-rust.ts	Updates Rust generator for canvas types/unions/commands/actions/errors.
scripts/generate-kotlin.ts	Updates Kotlin generator for canvas types/unions/commands/actions/errors.
scripts/generate-go.ts	Updates Go generator for canvas types/unions/commands/actions/errors.
scripts/generate-action-origin.ts	Extends action-origin generation to include canvas-scoped actions.
scripts/find-protocol-sources.ts	Adds channels-canvas to protocol source discovery.
schema/state.schema.json	Regenerates JSON schema to include CanvasState + session canvas fields/types.
schema/notifications.schema.json	Regenerates notification schema to include canvas-related state shapes.
docs/specification/subscriptions.md	Documents ahp-canvas: scheme + canvasReadResource in channel-scoped commands.
docs/specification/session-channel.md	Documents session-level canvas discovery fields and actions.
docs/specification/canvas-channel.md	Adds full Canvas Channel specification page (state/actions/commands/errors).
docs/guide/canvases.md	Adds a high-level “Canvases” guide describing roles and lifecycle.
docs/.vitepress/config.mts	Adds Canvases to guide/spec sidebar navigation.
clients/typescript/release-metadata.json	Adds 0.6.0 to supported protocol versions.
clients/typescript/CHANGELOG.md	Adds TypeScript client changelog entry for canvas support.
clients/swift/release-metadata.json	Adds 0.6.0 to supported protocol versions.
clients/swift/CHANGELOG.md	Adds Swift client changelog entry for canvas support.
clients/swift/AgentHostProtocol/Tests/AgentHostProtocolTests/FixtureDrivenReducerTests.swift	Adds fixture runner support for canvas reducer fixtures.
clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/MultiHostStateMirror.swift	Mirrors ahp-canvas: channels in the multi-host state mirror.
clients/swift/AgentHostProtocol/Sources/AgentHostProtocolClient/AHPStateMirror.swift	Mirrors ahp-canvas: channels in the single-host state mirror.
clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Reducers.swift	Adds session canvas handling + a canvas reducer implementation.
clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Version.generated.swift	Bumps generated Swift protocol version + supported versions.
clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Errors.generated.swift	Adds generated Swift error code/data for CanvasProviderError.
clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Commands.generated.swift	Adds generated Swift capability + canvas command structs.
clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/Actions.generated.swift	Adds generated Swift canvas/session actions + union wiring.
clients/rust/release-metadata.json	Adds 0.6.0 to supported protocol versions.
clients/rust/crates/ahp/tests/multi_host_state_mirror.rs	Updates Rust test helpers for new session canvas fields.
clients/rust/crates/ahp/src/reducers.rs	Adds session canvas reducers + new apply_action_to_canvas reducer.
clients/rust/crates/ahp/src/multi_host_state_mirror.rs	Mirrors ahp-canvas: channels in Rust multi-host state mirror.
clients/rust/crates/ahp-types/src/version.rs	Bumps Rust types crate protocol version + supported versions.
clients/rust/crates/ahp-types/src/state.rs	Adds Rust canvas types and session fields + snapshot state union update.
clients/rust/crates/ahp-types/src/errors.rs	Adds Rust CanvasProviderError code + data struct.
clients/rust/crates/ahp-types/src/commands.rs	Adds Rust ClientCapabilities.canvas + canvas command structs.
clients/rust/crates/ahp-types/src/actions.rs	Adds Rust canvas/session canvas actions + StateAction wiring.
clients/rust/CHANGELOG.md	Adds Rust client changelog entry for canvas support.
clients/kotlin/src/test/kotlin/com/microsoft/agenthostprotocol/FixtureDrivenReducerTest.kt	Adds Kotlin fixture runner support for canvas reducer fixtures.
clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/Reducers.kt	Adds Kotlin session canvas handling + canvas reducer implementation.
clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Version.generated.kt	Bumps generated Kotlin protocol version + supported versions.
clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Errors.generated.kt	Adds generated Kotlin error code/data for CanvasProviderError.
clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Commands.generated.kt	Adds generated Kotlin capability + canvas command structs.
clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Actions.generated.kt	Adds generated Kotlin canvas/session actions + union wiring.
clients/kotlin/release-metadata.json	Adds 0.6.0 to supported protocol versions.
clients/kotlin/CHANGELOG.md	Adds Kotlin client changelog entry for canvas support.
clients/go/release-metadata.json	Adds 0.6.0 to supported protocol versions.
clients/go/CHANGELOG.md	Adds Go client changelog entry for canvas support.
clients/go/ahptypes/version.generated.go	Bumps generated Go protocol version + supported versions.
clients/go/ahptypes/state.generated.go	Adds generated Go canvas types/session fields + snapshot union updates.
clients/go/ahptypes/errors.generated.go	Adds generated Go error code/data for CanvasProviderError.
clients/go/ahptypes/commands.generated.go	Adds generated Go capability + canvas command structs.
clients/go/ahptypes/actions.generated.go	Adds generated Go canvas/session actions + StateAction wiring.
clients/go/ahp/reducers.go	Adds Go session canvas handling + ApplyActionToCanvas reducer.
clients/go/ahp/reducers_fixture_test.go	Adds Go fixture runner support for canvas reducer fixtures.
CHANGELOG.md	Adds spec changelog entry describing the canvas channel addition.

Review details

• Files reviewed: 78/88 changed files
• Comments generated: 4
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 72/80 changed files
• Comments generated: 3
• Review effort level: Low

[connor4312]

Is this needed for a canvas the client publishes? The server isn't going to be consuming this most likely right?

[colbylwilliams]

It is consumed — just not by the transport. The agent reads description (and the per-operation descriptions) to decide when to open a canvas and what to invoke on it: the host folds it into the canvases section of the agent's system prompt and exposes it through the capability-listing tool, exactly the way ToolDefinition.description drives tool selection. The client is the source of truth for what its canvas does, so it publishes the description and the host aggregates it into SessionState.canvases. That's why it lives here rather than being server-consumed.

[connor4312]

What do these mean in the context of AHP? It doesn't know about extensions. We do know about plugins and customizations. Is that the right place for this?

[colbylwilliams]

Agreed — "extension" is borrowed vocabulary AHP doesn't own. Renamed to providerId, documented as an opaque namespace string AHP does not interpret. It's load-bearing rather than removable: canvasId is provider-local (two providers can each declare a diff canvas), so a namespace qualifier is needed to keep ids unique and to route canvasOpen/canvasInvokeOperation/canvasClose to the right provider. providerId lines up with the provider vocabulary already in the surface (canvasProviders, CanvasProviderSource, CanvasProviderError). I also dropped extensionName — displayName already carries the human-readable label.

[connor4312]

Do we need all these ID's? AHP doesn't know what a "provider" is. Channel URI should be enough to uniquely identify an open canvas, as they will already be unique.

[colbylwilliams]

Agreed. Trimmed OpenCanvasRef to { channel, canvasId, title?, availability } — the channel URI is now the sole identity (dropped instanceId, providerId, extensionName). I kept canvasId because the renderer keys the native surface type off it (editor vs browser vs a custom canvas), so a catalogue view can render the right thing without subscribing to every instance; title/availability are just for a lightweight list. Full identity now lives only on the CanvasState behind the channel.

[connor4312]

Does this need to be on the session state? If it's only client disconnects, I wonder if we should signal that in general for an activeClient vs specifically for the canvas alone

[colbylwilliams]

It's not only client disconnects, which is why it's per-instance. A provider can be server-side (host-internal) — no activeClient entry at all — yet its canvas can still go stale if the host tears the provider down. And one client can provide several canvases with independent lifecycles, so a client-level "connected" bit wouldn't tell a renderer whether the specific instance it's showing is still live. availability is the derived per-instance projection of "is this instance's resolved provider reachable", which is what a renderer needs to grey out a stale surface. It's redundant with activeClient state for the pure disconnect case, but it's the general signal that also covers the server-provider case — so I'd keep it on the canvas ref/state.

[connor4312]

"Operation" would match the existing wording we use for changesets

[colbylwilliams]

Done — renamed to match changesets: SessionCanvasAction → SessionCanvasOperation, the field actions → operations, and canvasInvokeAction → canvasInvokeOperation (actionName → operationName). I left the two channel state-mutation Actions (canvas/updated, canvas/closeRequested) as Actions, since those are protocol-level Actions in the same sense changesets keep both an operation vocabulary and channel Actions.

[connor4312]

If this channel encompasses an existing protocol and doesn't really need its own state or OOB messages, we can always do what we did with mcp:// or otel:// where we say that it's a channel that exists, refer to its own documentation for the protocol definition -- just with the addition of a channel: string for routing data to th eright place.

[colbylwilliams]

Agreed there's no need for its own OOB messages here — but it turns out there's also nothing to encompass. Canvas interaction is just three fixed RPCs (canvasOpen / canvasClose / canvasInvokeOperation) plus availability signals; provider→client never carries opaque data. So instead of a channel: string bridge I removed canvas/message outright. I also dropped the bespoke canvasReadResource path — content now rides the general, symmetrical resourceRead (which the relay already carries), so a canvas renders over a relay with no direct host connection. The channel keeps only the two state-mutation Actions (canvas/updated, canvas/closeRequested).