Add classical code generation workflow for typed event and RPC classes

[edburns]

Add classical code generation workflow for typed event and RPC classes

Fixes #69 .
Supersedes #79 .

Reviewer's Guide

The Big Idea

This PR replaces hand-written session event classes and raw rpc.invoke() calls with code-generated, strongly-typed Java classes produced by a TypeScript code generator (scripts/codegen/java.ts). The generator reads two JSON schemas distributed in the @github/copilot npm package (session-events.schema.json and api.schema.json) and emits:

1. Typed session events — a sealed class SessionEvent hierarchy with ~75 event subclasses (records) under src/generated/java/.../generated/, replacing the hand-written AbstractSessionEvent class and its ~55 inner classes plus the SessionEventParser in src/main/.../events/.

2. Typed RPC wrappers — ServerRpc and SessionRpc namespace classes with sub-API classes (e.g., SessionToolsApi, SessionUiApi, SessionPermissionsApi) under src/generated/java/.../generated/rpc/, giving compile-time safety to every JSON-RPC call.

The hand-coded events/ package (60 files, ~2900 lines) is deleted. All production code and tests are migrated to import from com.github.copilot.sdk.generated instead of com.github.copilot.sdk.events.

---

The Groups of Changed Files

1. Code Generation Infrastructure

These files define how the generated Java code is produced, validated, and updated.

• scripts/codegen/java.ts (1322 lines, new) — The TypeScript code generator. Reads session-events.schema.json and api.schema.json, emits Java sealed classes, records, enums, and RPC namespace API classes.
• scripts/codegen/package.json / package-lock.json — npm project pinning the @github/copilot@1.0.24 schema package as the generator's input.
• scripts/codegen/.gitignore — Ignores node_modules/.
• pom.xml — Three additions:
  • build-helper-maven-plugin adds src/generated/java as a source root
  • spotless-maven-plugin excludes src/generated/java/**/*.java from formatting
  • Two new profiles: codegen (runs npm ci + npm run generate) and update-schemas-from-npm-artifact (runs npm install @github/copilot@<version>)
• .github/workflows/codegen-check.yml (new) — CI workflow that re-runs the generator and fails if any committed generated file is stale.
• .github/workflows/update-copilot-dependency.yml (new) — Manual workflow: accepts a @github/copilot version, re-runs the generator, runs an AI-assisted schema verification step, and opens a PR.
• .gitattributes — Marks src/generated/java/** as linguist-generated=true (collapses diffs on GitHub) and eol=lf (cross-platform consistency).
• config/checkstyle/checkstyle.xml — Adds generated and rpc to the Checkstyle exclusion pattern.
• config/spotbugs/spotbugs-exclude.xml — Excludes generated packages from SpotBugs.
• docs/WORKFLOWS.md — Documents the two new workflows.

2. Agentic Sync Guardrails

These changes prevent the automated reference-implementation merge agent from hand-editing generated code.

• .github/prompts/agentic-merge-reference-impl.prompt.md — Adds an ABSOLUTE PROHIBITION block at the top forbidding any modification of src/generated/java/. The file mapping table now shows ❌ for dotnet/src/Generated/*.cs. A checklist item verifies no generated files were touched. A reminder is inserted before Step 5 (Apply Changes).
• .github/prompts/coding-agent-merge-reference-impl-instructions.md — Adds a corresponding prohibition block for the coding agent's instructions file.

3. Generated Code (Output)

All files under src/generated/java/com/github/copilot/sdk/generated/ (new). These are the output of java.ts and must never be hand-edited.

• Session events (~75 files) — SessionEvent.java (sealed base with @JsonTypeInfo/@JsonSubTypes polymorphic deserialization), individual event classes like AssistantMessageEvent, SessionIdleEvent, ToolExecutionCompleteEvent, etc., plus UnknownSessionEvent as the defaultImpl fallback.
• RPC types (~120 files) — ServerRpc.java, SessionRpc.java, sub-API classes (SessionToolsApi, SessionUiApi, etc.), and param/result records for every RPC method.
• Shared infra — RpcCaller.java (functional interface for invoke), RpcMapper.java (Jackson ObjectMapper holder).

4. Wiring: Delete Hand-Written Events, Switch to Generated Types

Production code changes that remove the old events package and wire in the generated replacements.

• src/main/.../events/ (60 files deleted) — The entire hand-written events package: AbstractSessionEvent, all ~55 event inner classes, SessionEventParser, and package-info.java.
• src/main/.../CopilotSession.java — The largest behavioral change file:
  • Imports switch from events.* to generated.*
  • Consumer<AbstractSessionEvent> → Consumer<SessionEvent> throughout
  • All raw rpc.invoke("session.xxx", Map.of(...), Object.class) calls replaced with typed getRpc().xxx.method(new XxxParams(...)) calls
  • New getRpc() method exposes SessionRpc (lazily created, double-checked locking)
  • setActiveSessionId() nulls sessionRpc so it re-creates with the new ID
  • Elicitation handling now uses generated enum types for actions
  • PermissionRequestedEvent.data.permissionRequest() is now Object (from the generic schema) — requires MAPPER.convertValue(...) to convert to the hand-written PermissionRequest DTO
  • New buildElicitationCancelParams() helper extracts repeated cancel-params construction
• src/main/.../CopilotClient.java — Connection record gains a ServerRpc serverRpc field, eagerly created. New getRpc() method exposes it.
• src/main/.../RpcHandlerDispatcher.java — SessionEventParser.parse(eventNode) replaced with MAPPER.treeToValue(eventNode, SessionEvent.class) (Jackson polymorphic deserialization via annotations).
• src/main/.../EventErrorHandler.java — Import change: AbstractSessionEvent → SessionEvent.
• src/main/.../json/SessionConfig.java / ResumeSessionConfig.java — Consumer<AbstractSessionEvent> → Consumer<SessionEvent> for the onEvent field.
• src/main/.../package-info.java — Javadoc reference update.

5. Documentation Updates

• README.md / jbang-example.java — Import paths changed from events.* to generated.*.
• src/site/markdown/ (8 files) — Cookbook pages, getting-started, advanced, and index all updated for the new import paths.
• .github/copilot-instructions.md — Adds generated to the package structure description.

6. Test Changes

• RpcWrappersTest.java (471 lines, new) — Comprehensive unit tests for ServerRpc and SessionRpc using an in-memory RpcCaller stub. Verifies correct method names, sessionId injection, param serialization.
• SessionEventParserTest.java → SessionEventDeserializationTest.java (renamed + rewritten) — Tests Jackson polymorphic deserialization of all event types via SessionEvent. Replaces the old SessionEventParser-based tests.
• TestUtil.java (101 lines, new) — Shared test utility for Windows CLI path resolution (findCopilotInPath()), extracting the logic that was previously duplicated in E2E tests.
• SessionEventsE2ETest.java — Uses TestUtil for CLI path finding; import changes.
• All other test files (15+ files) — Mechanical import changes from events.* to generated.*, plus AbstractSessionEvent → SessionEvent.

7. Review Fixes

Changes applied in response to review feedback on prior iterations:

• sendExpandedToolResult() bypass removed — The previous version needed a manual ObjectNode bypass because the generated SessionToolsHandlePendingToolCallParams.result was typed as String. The schema's anyOf[string, object] heuristic was fixed (multi-branch anyOf now falls back to Object), so ToolResultObject can be passed directly through the generated wrapper.
• fromValue() case sensitivity — Generated enum fromValue() uses case-sensitive equals(), which is correct for wire protocol values. Consumer code (e.g., elicitation action matching) uses equalsIgnoreCase() on the enum's getValue() string where case-insensitive matching is needed.

---

The Big Risks

1. Event deserialization fidelity after replacing SessionEventParser (HIGH)

The old SessionEventParser was a hand-written switch/map that parsed events from JSON. It is replaced by Jackson's @JsonTypeInfo + @JsonSubTypes polymorphic deserialization on the generated SessionEvent sealed class. This changes the deserialization path for every session event in the SDK.

What to check: The SessionEventDeserializationTest should cover all event types. Verify that:

• Unknown event types fall through to UnknownSessionEvent (the defaultImpl)
• visible = true on @JsonTypeInfo means the type field is populated on UnknownSessionEvent (preserving the wire type for forward compatibility)
• Event data records use @JsonIgnoreProperties(ignoreUnknown = true) so new fields from the server don't break deserialization

2. PermissionRequestedEvent.data.permissionRequest() is now Object (HIGH)

The generated event's permissionRequest field is typed as Object because the schema has no strong type for it. The code uses MAPPER.convertValue(data.permissionRequest(), PermissionRequest.class) to bridge to the hand-written DTO. If the wire shape changes, this convertValue will fail at runtime with no compile-time signal.

What to check: Look at the handleBroadcastEventAsync method in CopilotSession.java where convertValue is called. Confirm the E2E test for permissions exercises this path.

3. Lazy SessionRpc initialization and setActiveSessionId() reset (MEDIUM)

CopilotSession.getRpc() uses double-checked locking to lazily create a SessionRpc bound to the current sessionId. When setActiveSessionId() is called (on session resume when the server returns a different ID), it sets sessionRpc = null so the next call re-creates with the new ID.

What to check: The sessionRpc field is volatile and the lazy init uses synchronized(this). This is correct for double-checked locking. Since SessionRpc is stateless (just captures caller + sessionId), concurrent creation of duplicate instances is benign, but the synchronization prevents it anyway.

4. fromValue() is case-sensitive — intentional but surprising (MEDIUM)

Generated enum fromValue() methods use v.value.equals(value) (case-sensitive). If the server ever sends "Accept" instead of "accept" for an elicitation action, fromValue() throws IllegalArgumentException.

What to check: The consumer-facing code in CopilotSession correctly uses equalsIgnoreCase() on resp.action().getValue() when mapping to the SDK's ElicitationResultAction enum, so the user-facing API is case-tolerant. But internal paths that call fromValue() directly on generated enums (e.g., SessionUiHandlePendingElicitationParamsResultAction.fromValue(actionStr)) are case-sensitive. Verify this is intentional and matches the wire protocol.

5. Generated code is not reviewed line-by-line (MEDIUM)

~195 generated files (~10,000 lines) are committed as output of java.ts. The codegen-check.yml CI workflow verifies they're reproducible, and the update-copilot-dependency.yml workflow includes an AI-assisted spot-check step, but no human reviews every generated file.

What to check: Spot-check 2-3 generated API classes (e.g., SessionToolsApi.java, SessionUiApi.java) against the source api.schema.json to confirm method names, param types, and return types are correct. The RpcWrappersTest provides mechanical coverage.

6. CopilotClient.getRpc() throws on non-connected state (LOW)

The new getRpc() on CopilotClient throws IllegalStateException if connectionFuture is null, not done, or completed exceptionally. This is stricter than the old pattern where callers would just get the Connection from the future.

What to check: Confirm test coverage for calling getRpc() before start() (the CopilotClientTest should cover this).

---

Gotchas

The events/ package is entirely deleted, not deprecated

There is no deprecation bridge. All 60 files under src/main/.../events/ are removed in this PR. Any downstream code importing from com.github.copilot.sdk.events.* will fail to compile. The replacement is com.github.copilot.sdk.generated.*. This is acceptable because the SDK hasn't had a stable release with the old events package yet.

src/generated/java/ is FORBIDDEN for hand-editing

The files under src/generated/java/ must never be hand-edited — not by developers, and not by the agentic reference-implementation sync workflow. The correct way to update them is to trigger the update-copilot-dependency.yml workflow with a new @github/copilot npm version. The agentic-merge-reference-impl.prompt.md enforces this with an ABSOLUTE PROHIBITION block and a required stop-and-fail procedure.

.gitattributes marks generated code as linguist-generated

GitHub's PR diff will collapse src/generated/java/** by default. To inspect generated files, you need to expand them manually or use git diff locally.

build-helper-maven-plugin is required for src/generated/java to compile

The generated Java files live outside the standard src/main/java source root. The build-helper-maven-plugin adds src/generated/java as an additional source root during generate-sources. Without this plugin, the compiler won't find the generated types.

The update-copilot-dependency.yml workflow includes an AI code review step

After running the generator, the workflow invokes copilot --yolo with a verification prompt that asks the AI to spot-check 3 generated API classes against the JSON schema. This is a "trust but verify" guardrail. It requires a COPILOT_GITHUB_TOKEN secret and the .github/actions/setup-copilot composite action. If the AI finds mismatches, the workflow fails before creating the PR.

TestUtil extracts Windows CLI path resolution

On Windows, where.exe copilot can return multiple candidates (including Linux ELF binaries from VS Code's embedded Copilot CLI). TestUtil.findCopilotInPath() iterates all candidates and tries launching each one — this replaces duplicated logic that was previously in individual E2E test classes.

Elicitation mode field changed from String to enum

The generated ElicitationRequestedEvent types mode as an enum. The wiring code uses data.mode() != null ? data.mode().getValue() : null to convert back to a String for the ElicitationContext. This is a behavioral change: previously mode was a raw String from the JSON.

Two Maven profiles for codegen, used separately

• mvn generate-sources -Pcodegen — regenerates from the currently-pinned schema version
• mvn generate-sources -Pupdate-schemas-from-npm-artifact -Dcopilot.schema.version=1.0.25 — updates the pinned schema version (mutates package.json)

These are intentionally separate: the version bump is a distinct, explicit action.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR introduces a TypeScript-based code generation workflow that replaces hand-written session event DTOs and untyped JSON-RPC invocations with generated, strongly-typed Java event classes and RPC wrapper APIs.

Changes:

• Added a TypeScript code generator (scripts/codegen/java.ts) plus NPM project scaffolding to generate Java event/RPC types from JSON Schemas.
• Wired core SDK code to use generated SessionEvent types and typed ServerRpc/SessionRpc wrappers instead of the deleted events package and raw rpc.invoke(...) calls.
• Added Maven + CI workflow support to compile generated sources and verify generated code is in sync.

Show a summary per file

File	Description
scripts/codegen/java.ts	Implements codegen for event classes, RPC DTOs, and RPC wrapper APIs.
pom.xml	Adds generated source root + profiles to run/update codegen; excludes generated sources from Spotless.
src/main/java/com/github/copilot/sdk/CopilotSession.java	Switches event handling to SessionEvent and replaces raw RPC calls with typed session RPC wrappers.
src/main/java/com/github/copilot/sdk/CopilotClient.java	Adds typed server RPC access via ServerRpc and exposes getRpc().
src/main/java/com/github/copilot/sdk/RpcHandlerDispatcher.java	Switches session event parsing to Jackson polymorphic deserialization into generated SessionEvent.
.github/workflows/codegen-check.yml	CI workflow to fail if committed generated code is stale.
.github/workflows/update-copilot-dependency.yml	Workflow to bump @github/copilot schema version, regenerate, verify, and open a PR.

Copilot's findings

Files not reviewed (1)

• scripts/codegen/package-lock.json: Language not supported

• Files reviewed: 83/329 changed files
• Comments generated: 6