Add SDK canvas runtime support

[jmoseley]

What changed

Adds canvas runtime support across the Rust, Node, Python, Go, and .NET SDKs so consumers can declare canvases on session.create / session.resume, install a single CanvasHandler, and receive routed canvas.open / canvas.close / canvas.action.invoke JSON-RPC requests from the runtime. Resume surfaces openCanvases for rehydration, and host code can call session.canvas.* for native UI / chrome actions.

Per-language surface

• Rust (rust/src/canvas.rs): CanvasDeclaration, CanvasHandler trait, CanvasHostContext/CanvasOpenContext/CanvasActionContext/CanvasLifecycleContext, CanvasError, CanvasOpenResponse, ExtensionInfo. Wire types (OpenCanvasInstance, CanvasAction, CanvasInstanceAvailability, CanvasInvokeActionRequest/Result, etc.) consumed directly from generated::api_types — no duplication. Session::open_canvases() accessor; host APIs via session.rpc().canvas().
• Node (nodejs/src/canvas.ts): createCanvas, canvas declarations, handler contexts, errors, exports. Session create/resume thread canvases, requestCanvasRenderer, requestExtensions, extensionInfo.
• Python (python/copilot/canvas.py): CanvasHandler ABC with default on_close / on_action (raises canvas_action_no_handler). _jsonrpc loosened to allow arbitrary JSON return values for action results.
• Go (go/canvas.go): CanvasHandler interface + CanvasHandlerDefaults embeddable for partial impls. Inbound RPC registered via jsonrpc2.RequestHandlerFor with {code,message} error envelope.
• .NET (dotnet/src/Canvas.cs): idiomatic ICanvasHandler with async methods; same dispatch shape.

Java is intentionally not included in this PR and will follow separately.

Shared design

• App-side dispatch: SDK exposes a single CanvasHandler per session. Consumers switch on canvas_id themselves — no per-canvas registry inside the SDK.
• Generated wire types are imported directly from each language's codegen module; the hand-written canvas API is purely additive.
• Inbound RPC without a handler installed returns {"code":"canvas_handler_unset","message":"..."}.
• ExtensionInfo { source, name } lets consumers opt into stable agent-facing extension IDs (github-app:<provider-name>).

Notes for reviewers

Additive on top of the existing permission / user-input / tool handler models — no broad handler refactor. Canvas declarations require displayName. capabilities.ui.canvases is boolean. session.canvas.listOpen is a real RPC.

Validation

Per language:

• Rust: cargo +nightly-2026-04-14 fmt --check, cargo clippy --all-features --all-targets -- -D warnings, cargo test --all-features, cargo doc --no-deps --all-features
• Node: npm run typecheck, npm run lint, npx vitest run
• Python: uv run ruff format/check, uv run ty check copilot, uv run pytest
• Go: gofmt, go build/vet/test ./...
• .NET: dotnet format --verify-no-changes, dotnet build, dotnet test

[Copilot]

Pull request overview

This PR adds cross-SDK “canvas runtime” support, enabling SDK consumers to declare canvases, receive direct provider callbacks (canvas.*), and use host-side session.canvas.* RPCs with stable extension identity (extensionInfo)—without requiring the larger handler refactor from the prototype branch.

Changes:

• Rust: Introduces a new canvas module (declarations, handler traits, dispatch, host RPC types) and wires SessionConfig / ResumeSessionConfig to serialize canvas-related fields on session.create / session.resume.
• Rust: Adds Session::canvas() host API and updates the session event loop/router to handle direct provider callback requests (canvas.open|focus|reload|close|action.invoke).
• Node.js: Adds a canvas surface (createCanvas, types, dispatch), forwards canvas declarations + request flags + extensionInfo on session create/resume, and routes direct canvas.* JSON-RPC requests to registered canvases with tests.

Show a summary per file

File	Description
rust/tests/session_test.rs	Adds coverage for Rust canvas wire fields, provider dispatch routing, and SessionCanvas host API behavior.
rust/tests/e2e/elicitation.rs	Updates capability struct test to include the new ui.canvases field.
rust/src/wire.rs	Extends session create/resume wire payloads with canvases, request flags, and extension_info.
rust/src/types.rs	Adds ExtensionInfo, canvas config fields on session configs, resume result open-canvas capture, and UiCapabilities.canvases.
rust/src/session.rs	Adds SessionCanvas host API + open-canvas tracking and routes canvas.* provider callbacks through a per-session registry.
rust/src/router.rs	Adds debug logging when routing requests to a registered session.
rust/src/lib.rs	Exposes the new canvas module publicly.
rust/src/jsonrpc.rs	Adds debug logging for incoming JSON-RPC requests from the runtime.
rust/src/canvas.rs	New Rust canvas module: declarations, handler traits, registry + dispatch, request/response types, and unit tests.
nodejs/test/extension.test.ts	Verifies createCanvas is exported from the extension surface.
nodejs/test/client.test.ts	Adds tests for forwarding canvas fields on create/resume and for direct provider dispatch behavior.
nodejs/src/types.ts	Adds SessionCapabilities.ui.canvases, introduces ExtensionInfo, and extends session configs with canvas fields.
nodejs/src/session.ts	Adds per-session canvas registration and lookup to support direct dispatch routing.
nodejs/src/index.ts	Exports canvas APIs/types and ExtensionInfo from the main entrypoint.
nodejs/src/extension.ts	Exports canvas APIs/types and ExtensionInfo from the extension surface.
nodejs/src/client.ts	Forwards canvas fields on create/resume and registers handlers for direct canvas.* provider callbacks.
nodejs/src/canvas.ts	New Node canvas module: canvas declaration/types, createCanvas, and provider request dispatch helper.

Copilot's findings

• Files reviewed: 17/17 changed files
• Comments generated: 5

[ghost]

Generated by SDK Consistency Review Agent for issue #1401 · ● 11M

[ghost]

Cross-SDK Consistency Review 🔍

Overall, this is an impressively well-aligned multi-language implementation. The five SDKs (Rust, Node.js, Python, Go, .NET) are highly consistent on wire format, lifecycle callbacks (on_open/on_close/on_action), context types, ExtensionInfo, CanvasDeclaration, CanvasOpenResponse, and the session.canvas.* host-side RPC surface.

✅ Intentional Divergence (well-documented)

Node.js per-canvas factory vs single handler: The createCanvas() factory pattern in Node.js vs the single CanvasHandler per session in Rust/Python/Go/.NET is intentional and documented in nodejs/src/canvas.ts. Both target the same wire protocol. ✅

---

🔎 Minor Inconsistency Found

CanvasHostCapabilities is not a named type in Node.js

In all other SDKs, CanvasHostCapabilities is a named, exported type:

• Python: CanvasHostCapabilities dataclass exported in __all__
• Go: CanvasHostCapabilities struct exported from the package
• .NET: CanvasHostCapabilities sealed class (public)
• Rust: CanvasHostCapabilities struct (pub)

In Node.js however, the capabilities are typed inline:

// nodejs/src/canvas.ts line 67
export interface CanvasHostContext {
    capabilities?: {       // ← anonymous inline type
        canvases?: boolean;
    };
}

CanvasHostCapabilities is not exported from nodejs/src/index.ts.

This means Node.js consumers can't reference the capabilities type by name (e.g., to annotate a variable or destructure typed), while consumers in every other SDK can. A small addition to maintain parity:

/** Host capability details passed to canvas provider callbacks. */
export interface CanvasHostCapabilities {
    canvases?: boolean;
}

export interface CanvasHostContext {
    capabilities?: CanvasHostCapabilities;
}

...and export CanvasHostCapabilities from index.ts.

---

i️ Note on CanvasError.handler_unset()

Python exposes CanvasError.handler_unset() as a public class method, while other SDKs treat the unset-handler error as internal (e.g., .NET's CanvasErrorHelpers.HandlerUnset() is internal; Go and Rust construct it inline). This is a very minor surface inconsistency—consumers shouldn't normally need to construct this error—but worth noting for future cleanup.

---

✅ Everything Else

• All five SDKs expose open_canvases/OpenCanvases on the session ✅
• requestCanvasRenderer, requestExtensions, extensionInfo present in all five SessionConfig/create+resume params ✅
• CanvasDeclaration, CanvasOpenResponse, context types all structurally equivalent ✅
• canvas_handler_unset error code string matches across all SDKs ✅
• Java exclusion is documented and expected to follow separately ✅

Generated by SDK Consistency Review Agent for issue #1401 · ● 16.2M · ◷

[ghost]

Generated by SDK Consistency Review Agent for issue #1401 · ● 16.2M

[stephentoub]

This name confuses me a bit. Should this be specific to rendering, as elaborated on in the comment? It's not clear to me from "Canvases" that it's specific to rendering, and presumably there are other capabilities a canvas host will be capable of related to canvases.

[stephentoub]

Is this necessary? Doesn't seem like it provides much in the way of convenience.

[jmoseley]

CanvasHandlerBase is there for netstandard2.0 consumers — that target can't use default interface methods on ICanvasHandler, so without the base class every netstandard2.0 user has to write the OnCloseAsync no-op + OnActionAsync throw boilerplate themselves. Happy to drop it (and just put the boilerplate in the README) if you'd rather, but leaving as-is in #1420 — let me know if you want it removed in a follow-up.

[stephentoub]

Thanks, I think we should drop it. Implementing this will be rare, and the cited boilerplate is a trivial one-liner. Better to not add additional surface area to the namespace.

[stephentoub]

Is there a way we can add some good E2E tests in the SDK for this canvas support, in each language? We have a fairly extensive set of hundreds of E2E tests in each of the languages, and while we have some gaps we're working to fill, we're trying to make it so that we have great E2E coverage for every API exposed.

[SteveSandersonMS]

I added a tiny bit of E2E coverage in #1413 but @jmoseley will know better what other coverage would be valuable to add.