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
 
@@ -213,6 +213,8 @@ Test method names are converted to lowercase snake_case for snapshot filenames t
 
 ### What NOT to Modify
 
+- **DO NOT** edit, create, or delete any file under `src/generated/java/` — these are **auto-generated** by `scripts/codegen/java.ts` and will be overwritten. To update generated code, run `mvn generate-sources -Pcodegen` or trigger the `update-copilot-dependency.yml` workflow.
+   If you need to get a new version of the schemas, run `mvn generate-sources -Pupdate-schemas-from-npm-artifact` before running the code generator.
 - **DO NOT** edit `.github/agents/` directory - these contain instructions for other agents
 - **DO NOT** modify `target/` directory - this contains build artifacts
 - **DO NOT** edit `pom.xml` dependencies without careful consideration - this SDK has minimal dependencies by design

.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,144 @@
+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
+
+      - uses: ./.github/actions/setup-copilot
+
+      - name: Verify generated code against schema
+        env:
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+        run: |
+          cat > /tmp/verify-codegen-prompt.txt << 'PROMPT_EOF'
+          You are running inside the copilot-sdk-java repository.
+          The code generator has just run and produced Java source files under
+          src/generated/java/com/github/copilot/sdk/generated/rpc/.
+
+          Your task is to spot-check the generated API classes against the source
+          JSON schema to verify the generator produced correct output.
+
+          **Critical constraint: Do NOT modify any files. This is a read-only
+          verification. Use only read/inspect operations.**
+
+          **Steps:**
+          1. Read the API schema at:
+             scripts/codegen/node_modules/@github/copilot/schemas/api.schema.json
+
+          2. Pick these 3 generated API classes to verify:
+             - src/generated/java/com/github/copilot/sdk/generated/rpc/SessionToolsApi.java
+             - src/generated/java/com/github/copilot/sdk/generated/rpc/SessionUiApi.java
+             - src/generated/java/com/github/copilot/sdk/generated/rpc/SessionPermissionsApi.java
+
+          3. For each class, verify:
+             - Every RPC method in the schema's corresponding namespace has a
+               matching Java method in the generated class
+             - Parameter record fields match the JSON schema property names
+             - Java types are consistent with JSON schema types (String for
+               "string", Integer/int for "integer", Boolean/boolean for
+               "boolean", List for "array", Map or a generated class for
+               "object", etc.)
+             - No extra methods exist in the Java class that are not in the
+               schema
+
+          4. Print a summary table of what was checked and the result for each
+             method.
+
+          5. If ANY mismatch is found, print the details and exit with a
+             non-zero code.
+             If all checks pass, print "Schema verification passed" and exit 0.
+          PROMPT_EOF
+
+          copilot --yolo --prompt "$(cat /tmp/verify-codegen-prompt.txt)"
+
+      - 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>