Add classical code generation workflow for typed event and RPC classes

.gitattributes

@@ -1 +1,2 @@
-.github/workflows/*.lock.yml linguist-generated=true merge=ours
+.github/workflows/*.lock.yml linguist-generated=true merge=ours
+src/generated/java/** eol=lf linguist-generated=true

.github/copilot-instructions.md

@@ -77,7 +77,7 @@ mvn test -Dtest=CopilotClientTest
 
 - `com.github.copilot.sdk` - Core classes (CopilotClient, CopilotSession, JsonRpcClient)
 - `com.github.copilot.sdk.json` - DTOs, request/response types, handler interfaces (SessionConfig, MessageOptions, ToolDefinition, etc.)
-- `com.github.copilot.sdk.events` - Event types for session streaming (AssistantMessageEvent, SessionIdleEvent, ToolExecutionStartEvent, etc.)
+- `com.github.copilot.sdk.generated` - Generated event types for session streaming (SessionEvent, AssistantMessageEvent, SessionIdleEvent, ToolExecutionStartEvent, etc.)
 
 ### Test Infrastructure
 

.github/prompts/agentic-merge-reference-impl.prompt.md

@@ -2,6 +2,43 @@
 
 You are an expert Java developer tasked with porting changes from the reference implementation of the Copilot SDK (primarily the .NET implementation) to this Java SDK.
 
+## ❌❌❌ ABSOLUTE PROHIBITION: DO NOT TOUCH GENERATED CODE ❌❌❌
+
+> ### 🚫 THE FILES UNDER `src/generated/java/` ARE FORBIDDEN 🚫
+>
+> **NEVER, UNDER ANY CIRCUMSTANCES, MODIFY ANY FILE IN `src/generated/java/`.**
+>
+> These files are AUTO-GENERATED by `scripts/codegen/java.ts` and MUST NOT be hand-edited.
+> They are regenerated automatically when the `@github/copilot` npm package version is updated.
+>
+> ❌ DO NOT edit `src/generated/java/**/*.java`
+> ❌ DO NOT create new files in `src/generated/java/`
+> ❌ DO NOT delete files from `src/generated/java/`
+> ❌ DO NOT "fix" or "improve" generated code — it will be overwritten
+>
+> **IF ANY CHANGE YOU NEED TO MAKE REQUIRES TOUCHING `src/generated/java/`:**
+>
+> 1. **STOP IMMEDIATELY** — do not make the change
+> 2. **FAIL the agentic sync** — do not attempt to work around this restriction
+> 3. **Push an explanatory commit** with a message such as:
+>    ```
+>    SYNC BLOCKED: Required change needs generated code update
+>
+>    The reference implementation change '<description>' requires updates
+>    to the generated RPC/event types in src/generated/java/. These files
+>    cannot be hand-edited — they must be regenerated.
+>
+>    ACTION REQUIRED: Re-run the update-copilot-dependency.yml workflow
+>    to update the @github/copilot npm package and regenerate the Java
+>    source files before this sync can be completed.
+>    ```
+> 4. **Document in the PR body** which reference implementation changes were blocked and why
+> 5. **Do NOT attempt to work around this restriction** by making equivalent changes elsewhere
+>
+> The correct way to update generated code is:
+> - Trigger the `update-copilot-dependency.yml` workflow with the new `@github/copilot` version
+> - That workflow updates `package.json`, regenerates all files in `src/generated/java/`, and opens a PR
+
 ## ⚠️ IMPORTANT: Java SDK Design Takes Priority
 
 **The current design and architecture of the Java SDK is the priority.** When porting changes from the reference implementation:
@@ -101,7 +138,7 @@ For each change in the reference implementation diff, determine:
 | `dotnet/src/Client.cs`             | `src/main/java/com/github/copilot/sdk/CopilotClient.java` |
 | `dotnet/src/Session.cs`            | `src/main/java/com/github/copilot/sdk/CopilotSession.java` |
 | `dotnet/src/Types.cs`              | `src/main/java/com/github/copilot/sdk/types/*.java`    |
-| `dotnet/src/Generated/*.cs`        | `src/main/java/com/github/copilot/sdk/types/*.java`    |
+| `dotnet/src/Generated/*.cs`        | ❌ **DO NOT TOUCH** `src/generated/java/**` — see top of this file |
 | `dotnet/test/*.cs`                 | `src/test/java/com/github/copilot/sdk/*Test.java`      |
 | `docs/getting-started.md`          | `README.md` and `src/site/markdown/*.md`               |
 | `docs/*.md` (new files)            | `src/site/markdown/*.md` + update `src/site/site.xml`  |
@@ -111,6 +148,10 @@ For each change in the reference implementation diff, determine:
 
 ## Step 5: Apply Changes to Java SDK
 
+> ### ❌❌❌ REMINDER: `src/generated/java/` IS FORBIDDEN ❌❌❌
+> Any change that requires modifying `src/generated/java/` MUST stop the sync.
+> See the **ABSOLUTE PROHIBITION** section at the top of this file for required actions.
+
 When porting changes:
 
 ### ⚠️ Priority: Preserve Java SDK Design
@@ -400,6 +441,7 @@ Before finishing:
 
 ## Checklist
 
+- [ ] ❌ **VERIFIED: No files in `src/generated/java/` were modified** (if any were needed, sync was stopped per ABSOLUTE PROHIBITION above)
 - [ ] New branch created from `main`
 - [ ] Copilot CLI updated to latest version
 - [ ] README.md updated with minimum CLI version requirement
@@ -430,6 +472,7 @@ Before finishing:
 
 ## Notes
 
+- ❌❌❌ **`src/generated/java/` IS FORBIDDEN** — NEVER modify generated files; re-run `update-copilot-dependency.yml` instead ❌❌❌
 - The reference implementation SDK is at: `https://github.com/github/copilot-sdk.git`
 - Primary reference implementation is in `dotnet/` folder
 - This Java SDK targets Java 17+

.github/prompts/coding-agent-merge-reference-impl-instructions.md

@@ -17,3 +17,17 @@ Add the 'reference-impl-sync' label to the existing PR by running this command i
 If after analyzing the reference implementation diff there are no relevant changes to port to the Java SDK,
 push an empty commit with a message explaining why no changes were needed, so the PR reflects
 the analysis outcome. The repository maintainer will close the PR and issue manually.
+
+❌❌❌ ABSOLUTE PROHIBITION ❌❌❌
+
+NEVER MODIFY ANY FILE UNDER src/generated/java/ — THESE FILES ARE AUTO-GENERATED AND FORBIDDEN.
+
+If any change requires modifying src/generated/java/:
+1. STOP IMMEDIATELY — do not make the change
+2. FAIL the sync with an explanatory commit message
+3. Instruct the maintainer to re-run update-copilot-dependency.yml to regenerate these files
+
+See the ABSOLUTE PROHIBITION section in .github/prompts/agentic-merge-reference-impl.prompt.md
+for the full required procedure and commit message template.
+
+❌❌❌ END ABSOLUTE PROHIBITION ❌❌❌

.github/workflows/codegen-check.yml

@@ -0,0 +1,44 @@
+name: "Codegen Check"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - 'scripts/codegen/**'
+      - 'src/generated/java/**'
+      - '.github/workflows/codegen-check.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: "Verify generated files are up-to-date"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
+        with:
+          node-version: 22
+
+      - name: Install codegen dependencies
+        working-directory: ./scripts/codegen
+        run: npm ci
+
+      - name: Run codegen
+        working-directory: ./scripts/codegen
+        run: npm run generate
+
+      - name: Check for uncommitted changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "::error::Generated files are out of date. Run 'cd scripts/codegen && npm run generate' and commit the changes."
+            git diff --stat
+            git diff
+            exit 1
+          fi
+          echo "✅ Generated files are up-to-date"

.github/workflows/update-copilot-dependency.yml

@@ -0,0 +1,97 @@
+name: "Update @github/copilot Dependency"
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Target version of @github/copilot (e.g. 1.0.24)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    name: "Update @github/copilot to ${{ inputs.version }}"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate version input
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9._-]+)?$ ]]; then
+            echo "::error::Invalid version format '$VERSION'. Expected semver (e.g. 1.0.24)."
+            exit 1
+          fi
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
+        with:
+          node-version: 22
+
+      - name: Update @github/copilot in scripts/codegen
+        env:
+          VERSION: ${{ inputs.version }}
+        working-directory: ./scripts/codegen
+        # npm install updates package.json and package-lock.json to the new
+        # version; npm ci (below) then does a clean, reproducible install from
+        # the updated lock file.  Both steps are required: npm install alone
+        # leaves leftover packages, while npm ci alone cannot change the pinned
+        # version in the lock file.
+        run: npm install "@github/copilot@$VERSION"
+
+      - name: Install codegen dependencies
+        working-directory: ./scripts/codegen
+        run: npm ci
+
+      - name: Run codegen
+        working-directory: ./scripts/codegen
+        run: npm run generate
+
+      - name: Create pull request
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ inputs.version }}
+        run: |
+          BRANCH="update-copilot-$VERSION"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          if git rev-parse --verify "origin/$BRANCH" >/dev/null 2>&1; then
+            git checkout "$BRANCH"
+            git reset --hard HEAD
+          else
+            git checkout -b "$BRANCH"
+          fi
+
+          git add -A
+
+          if git diff --cached --quiet; then
+            echo "No changes detected; skipping commit and PR creation."
+            exit 0
+          fi
+
+          git commit -m "Update @github/copilot to $VERSION
+
+          - Updated @github/copilot in scripts/codegen
+          - Re-ran Java code generator"
+          git push origin "$BRANCH" --force-with-lease
+
+          if gh pr view "$BRANCH" >/dev/null 2>&1; then
+            echo "Pull request for branch '$BRANCH' already exists; updated branch only."
+          else
+            gh pr create \
+              --title "Update @github/copilot to $VERSION" \
+              --body "Automated update of \`@github/copilot\` to version \`$VERSION\`.
+
+          ### Changes
+          - Updated \`@github/copilot\` in \`scripts/codegen/package.json\`
+          - Re-ran Java code generator (\`scripts/codegen\`)
+
+          > Created by the **Update @github/copilot Dependency** workflow." \
+              --base main \
+              --head "$BRANCH"
+          fi

.gitignore

@@ -5,10 +5,11 @@ examples-test/
 blog-copilotsdk/
 .claude/worktrees
 smoke-test
-*job-logs.txt
+*job-logs.txt*
 temporary-prompts/
 changebundle.txt*
 .classpath
 .project
 .settings
+scripts/codegen/node_modules/
 *~

README.md

@@ -67,8 +67,8 @@ implementation 'com.github:copilot-sdk-java:0.2.2-java.1'
 
 ```java
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.events.AssistantMessageEvent;
-import com.github.copilot.sdk.events.SessionUsageInfoEvent;
+import com.github.copilot.sdk.generated.AssistantMessageEvent;
+import com.github.copilot.sdk.generated.SessionUsageInfoEvent;
 import com.github.copilot.sdk.json.CopilotClientOptions;
 import com.github.copilot.sdk.json.MessageOptions;
 import com.github.copilot.sdk.json.PermissionHandler;

config/checkstyle/checkstyle.xml

@@ -11,9 +11,9 @@
     <property name="charset" value="UTF-8"/>
     <property name="severity" value="error"/>
 
-    <!-- Exclude json package and events package (self-documenting DTOs) -->
+    <!-- Exclude json package, events package, and generated package (self-documenting DTOs) -->
     <module name="BeforeExecutionExclusionFileFilter">
-        <property name="fileNamePattern" value=".*[\\/](json|events)[\\/].*\.java$"/>
+        <property name="fileNamePattern" value=".*[\\/](json|events|generated|rpc)[\\/].*\.java$"/>
     </module>
 
     <module name="TreeWalker">

config/spotbugs/spotbugs-exclude.xml

@@ -2,15 +2,15 @@
 <!--
     SpotBugs exclusion filter for the Copilot SDK.
 
-    The 'events' and 'json' packages contain Jackson-deserialized DTOs where
+    The 'generated' and 'json' packages contain Jackson-deserialized DTOs where
     returning mutable internal representations (EI_EXPOSE_REP) and storing
     references to mutable objects (EI_EXPOSE_REP2) is intentional and expected.
     Making defensive copies would add overhead without meaningful security
     benefit for these read-only data transfer objects.
 -->
 <FindBugsFilter>
     <Match>
-        <Package name="com.github.copilot.sdk.events"/>
+        <Package name="com.github.copilot.sdk.generated"/>
         <Bug pattern="EI_EXPOSE_REP,EI_EXPOSE_REP2"/>
     </Match>
     <Match>

docs/WORKFLOWS.md

@@ -5,6 +5,8 @@
 | Workflow | Description | Triggers | Schedule |
 |----------|-------------|----------|----------|
 | [Build & Test](workflows/build-test.yml) | Builds, lints, and tests the Java SDK | `push` (main), `pull_request`, `merge_group`, `workflow_dispatch` | Sundays at 00:00 UTC |
+| [Codegen Check](workflows/codegen-check.yml) | Verifies that generated Java files are up-to-date with the JSON schemas | `push` (main), `pull_request`, `workflow_dispatch` | — |
+| [Update @github/copilot Dependency](workflows/update-copilot-dependency.yml) | Updates the `@github/copilot` npm package, re-runs code generation, and opens a PR | `workflow_dispatch` | — |
 | [Deploy Documentation](workflows/deploy-site.yml) | Generates and deploys versioned docs to GitHub Pages | `workflow_run` (after Build & Test), `release`, `workflow_dispatch` | — |
 | [Publish to Maven Central](workflows/publish-maven.yml) | Releases the SDK to Maven Central and creates a GitHub Release | `workflow_dispatch` | — |
 | [Weekly Reference Implementation Sync](workflows/weekly-reference-impl-sync.yml) | Checks for new reference implementation commits and creates an issue for Copilot to merge | `workflow_dispatch` | Mondays at 10:00 UTC |
@@ -87,6 +89,42 @@ Auto-generated compiled workflow produced by `gh aw compile` from the correspond
 
 ---
 
+## Codegen Check
+
+**File:** [`codegen-check.yml`](workflows/codegen-check.yml)
+
+Verifies that the generated Java source files in `src/generated/java/` are up-to-date with the JSON schemas distributed in the `@github/copilot` npm package.
+
+Steps:
+1. Installs the codegen dependencies from `scripts/codegen/`
+2. Runs the Java code generator (`npm run generate`)
+3. Fails with a diff if any generated file differs from what is committed
+
+Run this locally with:
+```bash
+cd scripts/codegen && npm ci && npm run generate
+```
+
+If changes appear, commit the updated generated files.
+
+---
+
+## Update @github/copilot Dependency
+
+**File:** [`update-copilot-dependency.yml`](workflows/update-copilot-dependency.yml)
+
+Manual workflow triggered when a new version of the `@github/copilot` npm package is published. Accepts a `version` input (e.g. `1.0.25`).
+
+Steps:
+1. Updates `@github/copilot` in `scripts/codegen/package.json`
+2. Re-runs the Java code generator
+3. Commits the updated `package.json`, `package-lock.json`, and all regenerated Java files
+4. Opens (or updates) a pull request for review
+
+The resulting PR will be automatically validated by the **Codegen Check** workflow.
+
+---
+
 ## Copilot Setup Steps
 
 **File:** [`copilot-setup-steps.yml`](workflows/copilot-setup-steps.yml)

jbang-example.java

@@ -1,8 +1,8 @@
 !
 //DEPS com.github:copilot-sdk-java:0.2.2-java.1
 import com.github.copilot.sdk.CopilotClient;
-import com.github.copilot.sdk.events.AssistantMessageEvent;
-import com.github.copilot.sdk.events.SessionUsageInfoEvent;
+import com.github.copilot.sdk.generated.AssistantMessageEvent;
+import com.github.copilot.sdk.generated.SessionUsageInfoEvent;
 import com.github.copilot.sdk.json.MessageOptions;
 import com.github.copilot.sdk.json.PermissionHandler;
 import com.github.copilot.sdk.json.SessionConfig;