Add open-canvases snapshot tracking to the Java SDK

[jmoseley]

What

Brings the Java SDK to parity with the other five SDK languages (Rust, Node, Python, Go, .NET) by maintaining an in-memory snapshot of the canvas instances currently open for a session. Java previously had none of this feature — only the generated event/data types existed — so this is net-new.

Behavior (mirrors the other 5 languages' contract exactly)

• CopilotSession keeps a lock-guarded List<OpenCanvasInstance> and exposes it via a new public accessor getOpenCanvases() (returns an immutable defensive copy).
• session.canvas.opened → upsert by instanceId. A provider-unregister re-emit arrives as another opened event with availability=stale and replaces the prior entry rather than duplicating it.
• session.canvas.closed → remove by instanceId (idempotent — removing an absent id is a no-op).
• Validation guardrails: opened requires non-empty instanceId/canvasId/extensionId and non-null availability; closed requires a non-empty instanceId. Invalid/empty/null payloads log the canonical failed to deserialize session.canvas.{opened,closed} payload warning and no-op. opened/stale events are never treated as removals.
• The update runs inside handleBroadcastEventAsync alongside the existing capabilities.changed passive state update, before user handlers observe the event, wrapped best-effort so snapshot upkeep can never disrupt event delivery.
• Resume/create seeding: the snapshot is seeded from the session.create / session.resume responses, which already carry openCanvases on the wire. Added the field to the hand-written CreateSessionResponse / ResumeSessionResponse records and seed via session.setOpenCanvases(...) after setCapabilities, matching .NET.

Tests

New SessionCanvasSnapshotTest (12 cases): open two → both present; close one → gone, other remains; idempotent absent close; empty + null instanceId no-op; missing-required-field opened ignored; stale re-emit replaces (no duplicate); getOpenCanvases() returns an immutable copy; seed via setOpenCanvases (incl. null-element filtering); null clears; plus Jackson deserialization tests for both response records. mvn spotless:apply && mvn verify is green.

Context

• Runtime events: copilot-agent-runtime #9489, shipped in CLI 1.0.60.
• Mirrors Handle session.canvas.closed by removing from open_canvases snapshot #1604, which landed the same opened-upsert + closed-remove behavior for Rust/Node/Python/Go/.NET (Java was deferred because it had no snapshot feature at all).
• Consumer: github-app's sticky-canvas fix.

Constraints honored

Java only. No edits to generated files (java/src/generated/) or other languages.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

Adds Java-side in-memory tracking of “open canvas instances” for a session, bringing the Java SDK in line with the existing snapshot behavior in the other language SDKs.

Changes:

• Added a lock-guarded open-canvases snapshot to CopilotSession, updated via session.canvas.opened (upsert) and session.canvas.closed (remove), and exposed via getOpenCanvases().
• Seeded the snapshot from session.create / session.resume RPC responses by adding openCanvases to the corresponding response records and wiring seeding in CopilotClient.
• Added unit tests covering upsert/remove, guardrails, stale re-emit replacement, seeding, and response deserialization.

Show a summary per file

File	Description
java/src/main/java/com/github/copilot/CopilotSession.java	Maintains and exposes the open-canvases snapshot; updates it during event dispatch.
java/src/main/java/com/github/copilot/CopilotClient.java	Seeds the session’s open-canvases snapshot from create/resume responses.
java/src/main/java/com/github/copilot/rpc/CreateSessionResponse.java	Adds openCanvases to the create-session response shape for seeding.
java/src/main/java/com/github/copilot/rpc/ResumeSessionResponse.java	Adds openCanvases to the resume-session response shape for seeding.
java/src/test/java/com/github/copilot/SessionCanvasSnapshotTest.java	New unit coverage for snapshot behavior + response deserialization.

Copilot's findings

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

[edburns]

Investigating the test failure now.

[github-actions]

Cross-SDK Consistency Review ✅

This PR successfully brings Java to parity with all five other SDK implementations for the open-canvases snapshot feature. Here's the cross-SDK consistency assessment:

API surface — naming is idiomatic and consistent

SDK	Public accessor	Return type
Node.js	session.openCanvases (getter)	OpenCanvasInstance[] (copy)
Python	session.open_canvases (property)	list[OpenCanvasInstance] (copy)
Go	session.OpenCanvases()	[]rpc.OpenCanvasInstance (copy)
.NET	session.OpenCanvases (property)	IReadOnlyList<OpenCanvasInstance>
Rust	session.open_canvases()	Vec<OpenCanvasInstance> (clone)
Java (this PR)	session.getOpenCanvases()	List<OpenCanvasInstance> (immutable copy)

All names follow language conventions. ✅

Behavior — all SDKs match

• session.canvas.opened → upsert by instanceId (stale re-emit replaces, not duplicates) ✅
• session.canvas.closed → idempotent remove by instanceId ✅
• Invalid/missing required fields → log warning, no-op ✅
• Return value is an immutable/defensive copy ✅
• Thread-safe snapshot (Java uses synchronized, Go uses sync.RWMutex, Rust uses parking_lot::RwLock, Python uses threading.Lock) ✅

One pre-existing inconsistency worth noting (not introduced by this PR)

This PR matches .NET's behavior of seeding openCanvases from both session.create and session.resume responses. However, Node.js, Python, Go, and Rust (as implemented in #1604) only seed from session.resume — their createSession implementations don't read openCanvases from the session.create response.

This gap predates this PR and is a minor behavioral difference: a freshly-created session in Node.js/Python/Go/Rust will always start with an empty canvas snapshot regardless of what the wire returns, while .NET and Java will correctly reflect any canvases the CLI reports at session creation time. Worth a follow-up to align Node.js/Python/Go/Rust with .NET+Java behavior.

This is not a blocker for merging this PR — Java's implementation is the more complete one here.

Generated by SDK Consistency Review Agent for issue #1606 · sonnet46 1.7M · ◷

[edburns]

This PR is solid and I'm +1 on merging it for Java parity.

Suggested follow-up: now that Java has the canvas snapshot foundation in place, this is a good time to invest in canvas ergonomics holistically across the SDK — not just for Java, but as a coordinated cross-language effort.

Concretely, the gap between Node's per-canvas factory pattern (createCanvas + per-action handler closures) and the single session-level CanvasHandler that the other five languages expose (where the caller is responsible for multiplexing by canvasId) is the most impactful thing to close. A thin, additive canvas-router helper — a canvasId-to-handler/action map that sits in front of the existing CanvasHandler interface — would substantially reduce boilerplate for implementors without touching any wire contracts or generated types.

The same "additive ergonomics over stable wire contracts" pattern applies to other areas too (elicitation helpers, plan-mode policy objects, SessionFS provider boilerplate), so it is worth writing a short cross-SDK ergonomics design note that sets naming and behavioral guardrails before we start building. But canvas is the right place to start: it is the newest surface, the cross-SDK inconsistency is already documented, and this PR gives Java the baseline needed to participate.