diff --git a/.claude/skills/agentic-merge-reference-impl/SKILL.md b/.claude/skills/agentic-merge-reference-impl/SKILL.md new file mode 100644 index 000000000..421ea147b --- /dev/null +++ b/.claude/skills/agentic-merge-reference-impl/SKILL.md @@ -0,0 +1,7 @@ +--- +name: agentic-merge-reference-impl +description: Merge reference implementation changes from the official Copilot SDK into this Java SDK. +license: MIT +--- + +Follow instructions in the [agentic-merge-reference-impl prompt](../../../.github/prompts/agentic-merge-reference-impl.prompt.md) to merge reference implementation changes from the official Copilot SDK into this Java SDK. diff --git a/.claude/skills/agentic-merge-upstream/SKILL.md b/.claude/skills/agentic-merge-upstream/SKILL.md deleted file mode 100644 index 32428db89..000000000 --- a/.claude/skills/agentic-merge-upstream/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: agentic-merge-upstream -description: Merge upstream changes from the official Copilot SDK into this Java SDK. -license: MIT ---- - -Follow instructions in the [agentic-merge-upstream prompt](../../../.github/prompts/agentic-merge-upstream.prompt.md) to merge upstream changes from the official Copilot SDK into this Java SDK. \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 284e2b800..c1a2d8dec 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -9,7 +9,7 @@ These instructions guide GitHub Copilot when assisting with this repository. The - **Tech Stack**: Java 17+, Maven, Jackson for JSON, JUnit for testing - **Purpose**: Provide a Java SDK for programmatic control of GitHub Copilot CLI - **Architecture**: JSON-RPC client communicating with Copilot CLI over stdio -- **Key Goals**: Maintain parity with upstream .NET SDK while following Java idioms +- **Key Goals**: Maintain parity with reference implementation .NET SDK while following Java idioms ## Build & Test Commands @@ -85,13 +85,13 @@ Tests use the official copilot-sdk test harness from `https://github.com/github/ - **E2ETestContext** - Manages test environment with CapiProxy for deterministic API responses - **CapiProxy** - Node.js-based replaying proxy using YAML snapshots from `test/snapshots/` -- Test snapshots are stored in the upstream repo's `test/snapshots/` directory +- Test snapshots are stored in the reference implementation repo's `test/snapshots/` directory ## Key Conventions -### Upstream Merging +### Reference Implementation Merging -This SDK tracks the official .NET implementation at `github/copilot-sdk`. The `.lastmerge` file contains the last merged upstream commit hash. Use the `agentic-merge-upstream` skill (see `.github/prompts/agentic-merge-upstream.prompt.md`) to port changes. +This SDK tracks the official .NET implementation at `github/copilot-sdk`. The `.lastmerge` file contains the last merged reference implementation commit hash. Use the `agentic-merge-reference-impl` skill (see `.github/prompts/agentic-merge-reference-impl.prompt.md`) to port changes. When porting from .NET: - Adapt to Java idioms, don't copy C# patterns directly @@ -217,7 +217,7 @@ Test method names are converted to lowercase snake_case for snapshot filenames t - **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 - **DO NOT** change the Jackson version without testing against all serialization patterns -- **DO NOT** modify test snapshots in `target/copilot-sdk/test/snapshots/` - these come from upstream +- **DO NOT** modify test snapshots in `target/copilot-sdk/test/snapshots/` - these come from reference implementation - **DO NOT** alter the Eclipse formatter configuration in `pom.xml` without team consensus - **DO NOT** remove or skip Checkstyle or Spotless checks @@ -278,7 +278,7 @@ The repository has a pre-commit hook (`.githooks/pre-commit`) that is **automati - Include tests for new functionality - Update documentation if adding/changing public APIs - Reference related issues using `#issue-number` -- For upstream merges, follow the `agentic-merge-upstream` skill workflow +- For reference implementation merges, follow the `agentic-merge-reference-impl` skill workflow ## Development Workflow @@ -299,12 +299,12 @@ The release process is automated via the `publish-maven.yml` GitHub Actions work - Converts the `## [Unreleased]` section to `## [version] - date` - Creates a new empty `## [Unreleased]` section at the top - Updates version comparison links at the bottom of CHANGELOG.md - - Injects the upstream SDK commit hash (from `.lastmerge`) as a `> **Upstream sync:**` blockquote in both the new `[Unreleased]` section and the released version section + - Injects the reference implementation SDK commit hash (from `.lastmerge`) as a `> **Reference implementation sync:**` blockquote in both the new `[Unreleased]` section and the released version section -2. **Upstream Sync Tracking**: Each release records which commit from the official `github/copilot-sdk` it is synced to: +2. **Reference Implementation Sync Tracking**: Each release records which commit from the official `github/copilot-sdk` it is synced to: - The `.lastmerge` file is read during the release workflow - The commit hash is injected into `CHANGELOG.md` under the release heading - - Format: `> **Upstream sync:** [\`github/copilot-sdk@SHORT_HASH\`](link-to-commit)` + - Format: `> **Reference implementation sync:** [\`github/copilot-sdk@SHORT_HASH\`](link-to-commit)` 3. **Documentation Updates**: README.md and jbang-example.java are updated with the new version. @@ -316,3 +316,4 @@ The release process is automated via the `publish-maven.yml` GitHub Actions work 5. **Rollback**: If the release fails, the documentation commit is automatically reverted The workflow is triggered manually via workflow_dispatch with optional version parameters. + diff --git a/.github/prompts/agentic-merge-upstream.prompt.md b/.github/prompts/agentic-merge-reference-impl.prompt.md similarity index 73% rename from .github/prompts/agentic-merge-upstream.prompt.md rename to .github/prompts/agentic-merge-reference-impl.prompt.md index c1d2c54a0..1c19b6f1c 100644 --- a/.github/prompts/agentic-merge-upstream.prompt.md +++ b/.github/prompts/agentic-merge-reference-impl.prompt.md @@ -1,15 +1,15 @@ -# Merge Upstream SDK Changes +# Merge Reference Implementation SDK Changes -You are an expert Java developer tasked with porting changes from the official Copilot SDK (primarily the .NET implementation) to this Java SDK. +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. ## ⚠️ IMPORTANT: Java SDK Design Takes Priority -**The current design and architecture of the Java SDK is the priority.** When porting changes from upstream: +**The current design and architecture of the Java SDK is the priority.** When porting changes from the reference implementation: -1. **Adapt, don't copy** - Translate upstream features to fit the Java SDK's existing patterns, naming conventions, and architecture +1. **Adapt, don't copy** - Translate reference implementation features to fit the Java SDK's existing patterns, naming conventions, and architecture 2. **Preserve Java idioms** - The Java SDK should feel natural to Java developers, not like a C# port 3. **Maintain consistency** - New code must match the existing codebase style and structure -4. **Evaluate before porting** - Not every upstream change needs to be ported; some may not be applicable or may conflict with Java SDK design decisions +4. **Evaluate before porting** - Not every reference implementation change needs to be ported; some may not be applicable or may conflict with Java SDK design decisions Before making any changes, **read and understand the existing Java SDK implementation** to ensure new code integrates seamlessly. @@ -19,50 +19,50 @@ The `.github/scripts/` directory contains helper scripts that automate the repea | Script | Purpose | |---|---| -| `.github/scripts/upstream-sync/merge-upstream-start.sh` | Creates branch, updates CLI, clones upstream, reads `.lastmerge`, prints commit summary | -| `.github/scripts/upstream-sync/merge-upstream-diff.sh` | Detailed diff analysis grouped by area (`.NET src`, tests, snapshots, docs, etc.) | -| `.github/scripts/upstream-sync/merge-upstream-finish.sh` | Runs format + test + build, updates `.lastmerge`, commits, pushes branch | +| `.github/scripts/reference-impl-sync/merge-reference-impl-start.sh` | Creates branch, updates CLI, clones reference implementation, reads `.lastmerge`, prints commit summary | +| `.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh` | Detailed diff analysis grouped by area (`.NET src`, tests, snapshots, docs, etc.) | +| `.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh` | Runs format + test + build, updates `.lastmerge`, commits, pushes branch | | `.github/scripts/build/format-and-test.sh` | Standalone `spotless:apply` + `mvn clean verify` (useful during porting too) | -All scripts write/read a `.merge-env` file (git-ignored) to share state (branch name, upstream dir, last-merge commit). +All scripts write/read a `.merge-env` file (git-ignored) to share state (branch name, reference-impl dir, last-merge commit). ## Workflow Overview -1. Run `./.github/scripts/upstream-sync/merge-upstream-start.sh` (creates branch, clones upstream, shows summary) -2. Run `./.github/scripts/upstream-sync/merge-upstream-diff.sh` (analyze changes) +1. Run `./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh` (creates branch, clones reference implementation, shows summary) +2. Run `./.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh` (analyze changes) 3. Update README with minimum CLI version requirement -4. Identify upstream changes to port +4. Identify reference implementation changes to port 5. Apply changes to Java SDK (commit as you go) -6. Port/adjust tests from upstream changes +6. Port/adjust tests from reference implementation changes 7. Run `./.github/scripts/build/format-and-test.sh` frequently while porting 8. Build the package -9. Update documentation (**required for every user-facing upstream change**) -10. Run `./.github/scripts/upstream-sync/merge-upstream-finish.sh` (final test + push) and finalize Pull Request (see note below about coding agent vs. manual workflow) +9. Update documentation (**required for every user-facing reference implementation change**) +10. Run `./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh` (final test + push) and finalize Pull Request (see note below about coding agent vs. manual workflow) 11. Perform final review before handing off --- -## Step 1: Initialize Upstream Sync +## Step 1: Initialize Reference Implementation Sync -Run the start script to create a branch, update the CLI, clone the upstream repo, and see a summary of new commits: +Run the start script to create a branch, update the CLI, clone the reference implementation repo, and see a summary of new commits: ```bash -./.github/scripts/upstream-sync/merge-upstream-start.sh +./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh ``` This writes a `.merge-env` file used by the other scripts. It outputs: - The branch name created - The Copilot CLI version -- The upstream dir path -- A short log of upstream commits since `.lastmerge` +- The reference-impl dir path +- A short log of reference implementation commits since `.lastmerge` -## Step 2: Analyze Upstream Changes +## Step 2: Analyze reference implementation Changes Run the diff script for a detailed breakdown by area: ```bash -./.github/scripts/upstream-sync/merge-upstream-diff.sh # stat only -./.github/scripts/upstream-sync/merge-upstream-diff.sh --full # full diffs +./.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh # stat only +./.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh --full # full diffs ``` The diff script groups changes into: .NET source, .NET tests, test snapshots, documentation, protocol/config, Go/Node.js/Python SDKs, and other files. @@ -80,13 +80,13 @@ git commit -m "Update Copilot CLI minimum version requirement" ## Step 4: Identify Changes to Port -Using the output from `merge-upstream-diff.sh`, focus on: +Using the output from `merge-reference-impl-diff.sh`, focus on: - `dotnet/src/` - Primary reference implementation - `dotnet/test/` - Test cases to port - `docs/` - Documentation updates - `sdk-protocol-version.json` - Protocol version changes -For each change in the upstream diff, determine: +For each change in the reference implementation diff, determine: 1. **New Features**: New methods, classes, or capabilities added to the SDK 2. **Bug Fixes**: Corrections to existing functionality @@ -96,7 +96,7 @@ For each change in the upstream diff, determine: ### Key Files to Compare -| Upstream (.NET) | Java SDK Equivalent | +| reference implementation (.NET) | Java SDK Equivalent | |------------------------------------|--------------------------------------------------------| | `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` | @@ -121,7 +121,7 @@ Before modifying any code: 2. **Identify the Java equivalent approach** - Don't replicate C# patterns; find the idiomatic Java way 3. **Check for existing abstractions** - The Java SDK may already have mechanisms that differ from .NET 4. **Preserve backward compatibility** - Existing API signatures should not break unless absolutely necessary -5. **When in doubt, match existing code** - Follow what's already in the Java SDK, not the upstream +5. **When in doubt, match existing code** - Follow what's already in the Java SDK, not the reference implementation ### Commit Changes Incrementally @@ -130,12 +130,12 @@ Before modifying any code: ```bash # After porting a feature or fix, commit with a descriptive message git add -git commit -m "Port from upstream" +git commit -m "Port from the reference implementation" # Example commits: -# git commit -m "Port new authentication flow from upstream" -# git commit -m "Add new message types from upstream protocol update" -# git commit -m "Port bug fix for session handling from upstream" +# git commit -m "Port new authentication flow from the reference implementation" +# git commit -m "Add new message types from the reference implementation protocol update" +# git commit -m "Port bug fix for session handling from the reference implementation" ``` This creates a clear history of changes that can be reviewed in the Pull Request. @@ -170,19 +170,19 @@ Follow the existing Java SDK patterns: - Use Java records for DTOs where appropriate - Follow the existing package structure under `com.github.copilot.sdk` - Maintain backward compatibility when possible -- **Match the style of surrounding code** - Consistency with existing code is more important than upstream patterns +- **Match the style of surrounding code** - Consistency with existing code is more important than reference implementation patterns - **Prefer existing abstractions** - If the Java SDK already solves a problem differently than .NET, keep the Java approach ## Step 6: Port Tests -After porting implementation changes, **always check for new or updated tests** in the upstream repository: +After porting implementation changes, **always check for new or updated tests** in the reference implementation repository: ### Check for New Tests ```bash cd "$TEMP_DIR/copilot-sdk" -git diff "$LAST_MERGE_COMMIT"..origin/main --stat -- dotnet/test/ -git diff "$LAST_MERGE_COMMIT"..origin/main --stat -- test/snapshots/ +git diff "$LAST_REFERENCE_IMPL_COMMIT"..origin/main --stat -- dotnet/test/ +git diff "$LAST_REFERENCE_IMPL_COMMIT"..origin/main --stat -- test/snapshots/ ``` ### Port Test Cases @@ -196,7 +196,7 @@ For each new or modified test file in `dotnet/test/`: ### Test File Mapping -| Upstream Test (.NET) | Java SDK Test | +| reference implementation Test (.NET) | Java SDK Test | |-----------------------------|--------------------------------------------------------| | `dotnet/test/AskUserTests.cs` | `src/test/java/com/github/copilot/sdk/AskUserTest.java` | | `dotnet/test/HooksTests.cs` | `src/test/java/com/github/copilot/sdk/HooksTest.java` | @@ -205,11 +205,11 @@ For each new or modified test file in `dotnet/test/`: ### Test Snapshot Compatibility -New test snapshots are stored in `test/snapshots/` in the upstream repository. These snapshots are automatically cloned during the Maven build process. +New test snapshots are stored in `test/snapshots/` in the reference implementation repository. These snapshots are automatically cloned during the Maven build process. If tests fail with errors like `TypeError: Cannot read properties of undefined`, the test harness may not yet support the new RPC methods. In this case: -1. **Mark tests as `@Disabled`** with a clear reason (e.g., `@Disabled("Requires test harness update with X support - see upstream PR #NNN")`) +1. **Mark tests as `@Disabled`** with a clear reason (e.g., `@Disabled("Requires test harness update with X support - see reference implementation PR #NNN")`) 2. **Document the dependency** in the test class Javadoc 3. **Enable tests later** once the harness is updated @@ -266,7 +266,7 @@ Verify: ## Step 9: Update Documentation -**Documentation is critical for new features.** Every new feature ported from upstream must be documented before the merge is complete. +**Documentation is critical for new features.** Every new feature ported from the reference implementation must be documented before the merge is complete. Review and complete this documentation checklist before proceeding to Step 10. If you determine no docs changes are needed, document that decision and rationale in the PR body under a clear heading (for example, `Documentation Impact`). @@ -328,31 +328,31 @@ Ensure consistency across all documentation files: Run the finish script which updates `.lastmerge`, runs a final build, and pushes the branch: ```bash -./.github/scripts/upstream-sync/merge-upstream-finish.sh # full format + test + push -./.github/scripts/upstream-sync/merge-upstream-finish.sh --skip-tests # if tests already passed +./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh # full format + test + push +./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh --skip-tests # if tests already passed ``` ### PR Handling: Coding Agent vs. Manual Workflow -**If running as a Copilot coding agent** (triggered via GitHub issue assignment by the weekly sync workflow), a pull request has **already been created automatically** for you. Do NOT create a new one. Just push your commits to the current branch — the existing PR will be updated. Add the `upstream-sync` label to the existing PR by running this command in a terminal: +**If running as a Copilot coding agent** (triggered via GitHub issue assignment by the weekly sync workflow), a pull request has **already been created automatically** for you. Do NOT create a new one. Just push your commits to the current branch — the existing PR will be updated. Add the `reference-impl-sync` label to the existing PR by running this command in a terminal: ```bash -gh pr edit --add-label "upstream-sync" +gh pr edit --add-label "reference-impl-sync" ``` -> **No-changes scenario (coding agent only):** If after analyzing the upstream 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. +> **No-changes scenario (coding agent only):** 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. **If running manually** (e.g., from VS Code via the reusable prompt), create the Pull Request using `gh` CLI or the GitHub MCP tool. Then add the label: ```bash -gh pr create --base main --title "Merge upstream SDK changes (YYYY-MM-DD)" --body-file /dev/stdin <<< "$PR_BODY" -gh pr edit --add-label "upstream-sync" +gh pr create --base main --title "Merge reference implementation SDK changes (YYYY-MM-DD)" --body-file /dev/stdin <<< "$PR_BODY" +gh pr edit --add-label "reference-impl-sync" ``` The PR body should include: -1. **Title**: `Merge upstream SDK changes (YYYY-MM-DD)` +1. **Title**: `Merge reference implementation SDK changes (YYYY-MM-DD)` 2. **Body** with: - - Summary of upstream commits analyzed (with count and commit range) + - Summary of reference implementation commits analyzed (with count and commit range) - Table of changes ported (commit hash + description) - List of changes intentionally not ported (with reasons) - Verification status (test count, build status) @@ -360,13 +360,13 @@ The PR body should include: ### PR Body Template ```markdown -## Upstream Merge +## Reference Implementation Merge Ports changes from the official Copilot SDK ([github/copilot-sdk](https://github.com/github/copilot-sdk)) since last merge (``→``). -### Upstream commits analyzed (N commits) +### Reference implementation commits analyzed (N commits) -- Brief description of each upstream change and whether it was ported or not +- Brief description of each reference implementation change and whether it was ported or not ### Changes ported @@ -403,11 +403,11 @@ Before finishing: - [ ] New branch created from `main` - [ ] Copilot CLI updated to latest version - [ ] README.md updated with minimum CLI version requirement -- [ ] Upstream repository cloned +- [ ] reference implementation repository cloned - [ ] Diff analyzed between `.lastmerge` commit and HEAD - [ ] New features/fixes identified - [ ] Changes ported to Java SDK following conventions -- [ ] **New/updated tests ported from upstream** (check `dotnet/test/` and `test/snapshots/`) +- [ ] **New/updated tests ported from the reference implementation** (check `dotnet/test/` and `test/snapshots/`) - [ ] Tests marked `@Disabled` if harness doesn't support new features yet - [ ] Changes committed incrementally with descriptive messages - [ ] `mvn test` passes @@ -418,22 +418,23 @@ Before finishing: - [ ] `src/site/markdown/documentation.md` updated for new basic usage - [ ] `src/site/markdown/advanced.md` updated for new advanced features - [ ] Javadoc added/updated for new public APIs -- [ ] If no documentation files were changed for user-facing upstream changes, PR body explicitly explains why documentation changes were not needed +- [ ] If no documentation files were changed for user-facing reference implementation changes, PR body explicitly explains why documentation changes were not needed - [ ] `src/site/site.xml` updated if new documentation pages were added - [ ] `.lastmerge` file updated with new commit hash - [ ] Branch pushed to remote - [ ] **Pull Request finalized** (coding agent: push to existing PR; manual: create via `mcp_github_create_pull_request`) -- [ ] **`upstream-sync` label added** to the PR via `mcp_github_add_issue_labels` +- [ ] **`reference-impl-sync` label added** to the PR via `mcp_github_add_issue_labels` - [ ] PR URL provided to user --- ## Notes -- The upstream SDK is at: `https://github.com/github/copilot-sdk.git` +- 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+ - Uses Jackson for JSON processing - Uses JUnit 5 for testing -- **Java SDK design decisions take precedence over upstream patterns** -- **Adapt upstream changes to fit Java idioms, not the other way around** +- **Java SDK design decisions take precedence over reference implementation patterns** +- **Adapt reference implementation changes to fit Java idioms, not the other way around** + diff --git a/.github/prompts/coding-agent-merge-instructions.md b/.github/prompts/coding-agent-merge-reference-impl-instructions.md similarity index 50% rename from .github/prompts/coding-agent-merge-instructions.md rename to .github/prompts/coding-agent-merge-reference-impl-instructions.md index 1c18e1f5f..cee6ef8a7 100644 --- a/.github/prompts/coding-agent-merge-instructions.md +++ b/.github/prompts/coding-agent-merge-reference-impl-instructions.md @@ -1,8 +1,8 @@ - - + + -Follow the agentic-merge-upstream prompt at .github/prompts/agentic-merge-upstream.prompt.md -to port upstream changes to the Java SDK. +Follow the agentic-merge-reference-impl prompt at .github/prompts/agentic-merge-reference-impl.prompt.md +to port reference implementation changes to the Java SDK. Use the utility scripts in .github/scripts/ subfolders for initialization, diffing, formatting, and testing. Commit changes incrementally. Update .lastmerge when done. @@ -10,10 +10,10 @@ Commit changes incrementally. Update .lastmerge when done. IMPORTANT: A pull request has already been created automatically for you — do NOT create a new one. Push your commits to the current branch, and the existing PR will be updated. -Add the 'upstream-sync' label to the existing PR by running this command in a terminal: +Add the 'reference-impl-sync' label to the existing PR by running this command in a terminal: - gh pr edit --add-label "upstream-sync" + gh pr edit --add-label "reference-impl-sync" -If after analyzing the upstream diff there are no relevant changes to port to the Java SDK, +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. diff --git a/.github/scripts/upstream-sync/merge-upstream-diff.sh b/.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh similarity index 86% rename from .github/scripts/upstream-sync/merge-upstream-diff.sh rename to .github/scripts/reference-impl-sync/merge-reference-impl-diff.sh index ee61b6ffc..8ff870103 100755 --- a/.github/scripts/upstream-sync/merge-upstream-diff.sh +++ b/.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh @@ -1,8 +1,8 @@ #!/usr/bin/env bash # ────────────────────────────────────────────────────────────── -# merge-upstream-diff.sh +# merge-reference-impl-diff.sh # -# Generates a detailed diff analysis of upstream changes since +# Generates a detailed diff analysis of reference implementation changes since # the last merge, grouped by area of interest: # • .NET source (primary reference) # • .NET tests @@ -10,10 +10,10 @@ # • Documentation # • Protocol / config files # -# Usage: ./.github/scripts/upstream-sync/merge-upstream-diff.sh [--full] +# Usage: ./.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh [--full] # --full Show actual diffs, not just stats # -# Requires: .merge-env written by merge-upstream-start.sh +# Requires: .merge-env written by merge-reference-impl-start.sh # ────────────────────────────────────────────────────────────── set -euo pipefail @@ -21,7 +21,7 @@ ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)" ENV_FILE="$ROOT_DIR/.merge-env" if [[ ! -f "$ENV_FILE" ]]; then - echo "❌ $ENV_FILE not found. Run ./.github/scripts/upstream-sync/merge-upstream-start.sh first." + echo "❌ $ENV_FILE not found. Run ./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh first." exit 1 fi @@ -33,13 +33,13 @@ if [[ "${1:-}" == "--full" ]]; then SHOW_FULL=true fi -cd "$UPSTREAM_DIR" +cd "$REFERENCE_IMPL_DIR" git fetch origin main 2>/dev/null RANGE="$LAST_MERGE_COMMIT..origin/main" echo "════════════════════════════════════════════════════════════" -echo " Upstream diff analysis: $RANGE" +echo " Reference implementation diff analysis: $RANGE" echo "════════════════════════════════════════════════════════════" # ── Commit log ──────────────────────────────────────────────── @@ -82,5 +82,5 @@ section "Other files" "README.md" "CONTRIBUTING.md" "SECURIT echo "════════════════════════════════════════════════════════════" echo " To see full diffs: $0 --full" echo " To see a specific path:" -echo " cd $UPSTREAM_DIR && git diff $RANGE -- " +echo " cd $REFERENCE_IMPL_DIR && git diff $RANGE -- " echo "════════════════════════════════════════════════════════════" diff --git a/.github/scripts/upstream-sync/merge-upstream-finish.sh b/.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh similarity index 72% rename from .github/scripts/upstream-sync/merge-upstream-finish.sh rename to .github/scripts/reference-impl-sync/merge-reference-impl-finish.sh index 1663ef259..480d43bc0 100755 --- a/.github/scripts/upstream-sync/merge-upstream-finish.sh +++ b/.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh @@ -1,17 +1,17 @@ #!/usr/bin/env bash # ────────────────────────────────────────────────────────────── -# merge-upstream-finish.sh +# merge-reference-impl-finish.sh # -# Finalises an upstream merge: +# Finalises a reference implementation merge: # 1. Runs format + test + build (via format-and-test.sh) -# 2. Updates .lastmerge to upstream HEAD +# 2. Updates .lastmerge to reference implementation HEAD # 3. Commits the .lastmerge update # 4. Pushes the branch to origin # -# Usage: ./.github/scripts/upstream-sync/merge-upstream-finish.sh -# ./.github/scripts/upstream-sync/merge-upstream-finish.sh --skip-tests +# Usage: ./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh +# ./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh --skip-tests # -# Requires: .merge-env written by merge-upstream-start.sh +# Requires: .merge-env written by merge-reference-impl-start.sh # ────────────────────────────────────────────────────────────── set -euo pipefail @@ -19,7 +19,7 @@ ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)" ENV_FILE="$ROOT_DIR/.merge-env" if [[ ! -f "$ENV_FILE" ]]; then - echo "❌ $ENV_FILE not found. Run ./.github/scripts/upstream-sync/merge-upstream-start.sh first." + echo "❌ $ENV_FILE not found. Run ./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh first." exit 1 fi @@ -45,7 +45,7 @@ fi # ── 2. Update .lastmerge ───────────────────────────────────── echo "▸ Updating .lastmerge…" -NEW_COMMIT=$(cd "$UPSTREAM_DIR" && git rev-parse origin/main) +NEW_COMMIT=$(cd "$REFERENCE_IMPL_DIR" && git rev-parse origin/main) echo "$NEW_COMMIT" > "$ROOT_DIR/.lastmerge" git add .lastmerge @@ -59,5 +59,5 @@ echo "" echo "✅ Branch pushed. Next step:" echo " Create a Pull Request (base: main, head: $BRANCH_NAME)" echo "" -echo " Suggested title: Merge upstream SDK changes ($(date +%Y-%m-%d))" -echo " Don't forget to add the 'upstream-sync' label." +echo " Suggested title: Merge reference implementation SDK changes ($(date +%Y-%m-%d))" +echo " Don't forget to add the 'reference-impl-sync' label." diff --git a/.github/scripts/upstream-sync/merge-upstream-start.sh b/.github/scripts/reference-impl-sync/merge-reference-impl-start.sh similarity index 68% rename from .github/scripts/upstream-sync/merge-upstream-start.sh rename to .github/scripts/reference-impl-sync/merge-reference-impl-start.sh index 755361cd1..76408e4ec 100755 --- a/.github/scripts/upstream-sync/merge-upstream-start.sh +++ b/.github/scripts/reference-impl-sync/merge-reference-impl-start.sh @@ -1,15 +1,15 @@ #!/usr/bin/env bash # ────────────────────────────────────────────────────────────── -# merge-upstream-start.sh +# merge-reference-impl-start.sh # -# Prepares the workspace for an upstream merge: +# Prepares the workspace for a reference implementation merge: # 1. Creates a dated branch from main # 2. Updates Copilot CLI and records the new version -# 3. Clones the upstream copilot-sdk repo into a temp dir +# 3. Clones the reference implementation copilot-sdk repo into a temp dir # 4. Reads .lastmerge and prints a short summary of new commits # -# Usage: ./.github/scripts/upstream-sync/merge-upstream-start.sh -# Output: Exports UPSTREAM_DIR and LAST_MERGE_COMMIT to a +# Usage: ./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh +# Output: Exports REFERENCE_IMPL_DIR and LAST_MERGE_COMMIT to a # .merge-env file so other scripts can source it. # ────────────────────────────────────────────────────────────── set -euo pipefail @@ -17,7 +17,7 @@ set -euo pipefail ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)" cd "$ROOT_DIR" -UPSTREAM_REPO="https://github.com/github/copilot-sdk.git" +REFERENCE_IMPL_REPO="https://github.com/github/copilot-sdk.git" ENV_FILE="$ROOT_DIR/.merge-env" # ── 1. Create branch (or reuse existing) ───────────────────── @@ -33,7 +33,7 @@ else echo "▸ Ensuring main is up to date…" git pull origin main - BRANCH_NAME="merge-upstream-$(date +%Y%m%d)" + BRANCH_NAME="merge-reference-impl-$(date +%Y%m%d)" echo "▸ Creating branch: $BRANCH_NAME" git checkout -b "$BRANCH_NAME" fi @@ -49,11 +49,11 @@ else CLI_VERSION="UNKNOWN" fi -# ── 3. Clone upstream ──────────────────────────────────────── +# ── 3. Clone reference implementation ──────────────────────────────────────── TEMP_DIR=$(mktemp -d) -UPSTREAM_DIR="$TEMP_DIR/copilot-sdk" -echo "▸ Cloning upstream into $UPSTREAM_DIR …" -git clone --depth=200 "$UPSTREAM_REPO" "$UPSTREAM_DIR" +REFERENCE_IMPL_DIR="$TEMP_DIR/copilot-sdk" +echo "▸ Cloning reference implementation into $REFERENCE_IMPL_DIR …" +git clone --depth=200 "$REFERENCE_IMPL_REPO" "$REFERENCE_IMPL_DIR" # ── 4. Read last merge commit ──────────────────────────────── if [[ ! -f "$ROOT_DIR/.lastmerge" ]]; then @@ -61,21 +61,21 @@ if [[ ! -f "$ROOT_DIR/.lastmerge" ]]; then exit 1 fi LAST_MERGE_COMMIT=$(tr -d '[:space:]' < "$ROOT_DIR/.lastmerge") -echo "▸ Last merged upstream commit: $LAST_MERGE_COMMIT" +echo "▸ Last merged reference implementation commit: $LAST_MERGE_COMMIT" # Quick summary echo "" -echo "── Upstream commits since last merge ──" -(cd "$UPSTREAM_DIR" && git fetch origin main && \ +echo "── Reference implementation commits since last merge ──" +(cd "$REFERENCE_IMPL_DIR" && git fetch origin main && \ git log --oneline "$LAST_MERGE_COMMIT"..origin/main) || \ echo " (could not generate log – the commit may have been rebased)" echo "" # ── 5. Write env file for other scripts ────────────────────── cat > "$ENV_FILE" < [upstream-hash] +# Usage: ./update-changelog.sh [reference-impl-hash] # Example: ./update-changelog.sh 1.0.8 # Example: ./update-changelog.sh 1.0.8 05e3c46c8c23130c9c064dc43d00ec78f7a75eab if [ -z "$1" ]; then echo "Error: Version argument required" - echo "Usage: $0 [upstream-hash]" + echo "Usage: $0 [reference-impl-hash]" exit 1 fi VERSION="$1" -UPSTREAM_HASH="${2:-}" +REFERENCE_IMPL_HASH="${2:-}" CHANGELOG_FILE="${CHANGELOG_FILE:-CHANGELOG.md}" RELEASE_DATE=$(date +%Y-%m-%d) echo "Updating CHANGELOG.md for version ${VERSION} (${RELEASE_DATE})" -if [ -n "$UPSTREAM_HASH" ]; then - echo " Upstream SDK sync: ${UPSTREAM_HASH:0:7}" +if [ -n "$REFERENCE_IMPL_HASH" ]; then + echo " Reference implementation SDK sync: ${REFERENCE_IMPL_HASH:0:7}" fi # Check if CHANGELOG.md exists @@ -38,7 +38,7 @@ fi TEMP_FILE=$(mktemp) # Process the CHANGELOG -awk -v version="$VERSION" -v date="$RELEASE_DATE" -v upstream_hash="$UPSTREAM_HASH" ' +awk -v version="$VERSION" -v date="$RELEASE_DATE" -v REFERENCE_IMPL_HASH="$REFERENCE_IMPL_HASH" ' BEGIN { unreleased_found = 0 content_found = 0 @@ -65,26 +65,26 @@ links_section && repo_url == "" && /^\[[0-9]+\.[0-9]+\.[0-9]+(-java\.[0-9]+)?\]: if (!unreleased_found) { print "## [Unreleased]" print "" - if (upstream_hash != "") { - short_hash = substr(upstream_hash, 1, 7) - print "> **Upstream sync:** [`github/copilot-sdk@" short_hash "`](https://github.com/github/copilot-sdk/commit/" upstream_hash ")" + if (REFERENCE_IMPL_HASH != "") { + short_hash = substr(REFERENCE_IMPL_HASH, 1, 7) + print "> **Reference implementation sync:** [`github/copilot-sdk@" short_hash "`](https://github.com/github/copilot-sdk/commit/" REFERENCE_IMPL_HASH ")" print "" } print "## [" version "] - " date - if (upstream_hash != "") { + if (REFERENCE_IMPL_HASH != "") { print "" - print "> **Upstream sync:** [`github/copilot-sdk@" short_hash "`](https://github.com/github/copilot-sdk/commit/" upstream_hash ")" + print "> **Reference implementation sync:** [`github/copilot-sdk@" short_hash "`](https://github.com/github/copilot-sdk/commit/" REFERENCE_IMPL_HASH ")" } unreleased_found = 1 - skip_old_upstream = 1 + skip_old_reference_impl = 1 next } } -# Skip the old upstream sync line and surrounding blank lines from the previous [Unreleased] section -skip_old_upstream && /^[[:space:]]*$/ { next } -skip_old_upstream && /^> \*\*Upstream sync:\*\*/ { next } -skip_old_upstream && !/^[[:space:]]*$/ && !/^> \*\*Upstream sync:\*\*/ { skip_old_upstream = 0 } +# Skip the old Reference implementation sync line and surrounding blank lines from the previous [Unreleased] section +skip_old_reference_impl && /^[[:space:]]*$/ { next } +skip_old_reference_impl && /^> \*\*Reference implementation sync:\*\*/ { next } +skip_old_reference_impl && !/^[[:space:]]*$/ && !/^> \*\*Reference implementation sync:\*\*/ { skip_old_reference_impl = 0 } # Capture the first version link to get the previous version links_section && first_version_link == "" && /^\[[0-9]+\.[0-9]+\.[0-9]+(-java\.[0-9]+)?\]:/ { @@ -119,3 +119,4 @@ echo "✓ CHANGELOG.md updated successfully" echo " - Added version ${VERSION} with date ${RELEASE_DATE}" echo " - Created new [Unreleased] section" echo " - Updated version comparison links" + diff --git a/.github/skills/agentic-merge-reference-impl/SKILL.md b/.github/skills/agentic-merge-reference-impl/SKILL.md new file mode 100644 index 000000000..43addbac4 --- /dev/null +++ b/.github/skills/agentic-merge-reference-impl/SKILL.md @@ -0,0 +1,7 @@ +--- +name: agentic-merge-reference-impl +description: Merge reference implementation changes from the official Copilot SDK into this Java SDK. +license: MIT +--- + +Follow instructions in the [agentic-merge-reference-impl prompt](../../prompts/agentic-merge-reference-impl.prompt.md) to merge reference implementation changes from the official Copilot SDK into this Java SDK. diff --git a/.github/skills/agentic-merge-upstream/SKILL.md b/.github/skills/agentic-merge-upstream/SKILL.md deleted file mode 100644 index 14301c27d..000000000 --- a/.github/skills/agentic-merge-upstream/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: agentic-merge-upstream -description: Merge upstream changes from the official Copilot SDK into this Java SDK. -license: MIT ---- - -Follow instructions in the [agentic-merge-upstream prompt](../../prompts/agentic-merge-upstream.prompt.md) to merge upstream changes from the official Copilot SDK into this Java SDK. \ No newline at end of file diff --git a/.github/workflows/publish-maven.yml b/.github/workflows/publish-maven.yml index 242853209..540da6ae7 100644 --- a/.github/workflows/publish-maven.yml +++ b/.github/workflows/publish-maven.yml @@ -108,14 +108,14 @@ jobs: run: | VERSION="${{ steps.versions.outputs.release_version }}" - # Read the upstream SDK commit hash that this release is synced to - UPSTREAM_HASH=$(cat .lastmerge) - UPSTREAM_SHORT="${UPSTREAM_HASH:0:7}" - UPSTREAM_URL="https://github.com/github/copilot-sdk/commit/${UPSTREAM_HASH}" - echo "Upstream SDK sync: ${UPSTREAM_SHORT} (${UPSTREAM_URL})" + # Read the reference implementation SDK commit hash that this release is synced to + REFERENCE_IMPL_HASH=$(cat .lastmerge) + REFERENCE_IMPL_SHORT="${REFERENCE_IMPL_HASH:0:7}" + REFERENCE_IMPL_URL="https://github.com/github/copilot-sdk/commit/${REFERENCE_IMPL_HASH}" + echo "Reference implementation SDK sync: ${REFERENCE_IMPL_SHORT} (${REFERENCE_IMPL_URL})" - # Update CHANGELOG.md with release version and upstream sync hash - ./.github/scripts/release/update-changelog.sh "${VERSION}" "${UPSTREAM_HASH}" + # Update CHANGELOG.md with release version and Reference implementation sync hash + ./.github/scripts/release/update-changelog.sh "${VERSION}" "${REFERENCE_IMPL_HASH}" # Update version in README.md (supports versions like 1.0.0 and 0.1.32-java.0) sed -i "s|[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\(-java\.[0-9][0-9]*\)\{0,1\}|${VERSION}|g" README.md @@ -249,3 +249,4 @@ jobs: -f publish_as_latest=true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + diff --git a/.github/workflows/weekly-upstream-sync.lock.yml b/.github/workflows/weekly-reference-impl-sync.lock.yml similarity index 97% rename from .github/workflows/weekly-upstream-sync.lock.yml rename to .github/workflows/weekly-reference-impl-sync.lock.yml index c2bceee20..25de1e1e8 100644 --- a/.github/workflows/weekly-upstream-sync.lock.yml +++ b/.github/workflows/weekly-reference-impl-sync.lock.yml @@ -21,12 +21,12 @@ # # For more information: https://github.github.com/gh-aw/introduction/overview/ # -# Weekly upstream sync workflow. Checks for new commits in the official +# Weekly reference implementation sync workflow. Checks for new commits in the official # Copilot SDK (github/copilot-sdk) and assigns to Copilot to port changes. # # gh-aw-metadata: {"schema_version":"v1","frontmatter_hash":"fc14b09206c7aeafcd52c843adce996a1c14cf15875f9b647ef71f631b3b296e","compiler_version":"v0.51.6"} -name: "Weekly Upstream Sync Agentic Workflow" +name: "Weekly Reference Implementation Sync Agentic Workflow" "on": schedule: - cron: "39 8 * * 2" @@ -38,7 +38,7 @@ permissions: {} concurrency: group: "gh-aw-${{ github.workflow }}" -run-name: "Weekly Upstream Sync Agentic Workflow" +run-name: "Weekly Reference Implementation Sync Agentic Workflow" jobs: activation: @@ -64,7 +64,7 @@ jobs: GH_AW_INFO_VERSION: "" GH_AW_INFO_AGENT_VERSION: "0.0.420" GH_AW_INFO_CLI_VERSION: "v0.51.6" - GH_AW_INFO_WORKFLOW_NAME: "Weekly Upstream Sync Agentic Workflow" + GH_AW_INFO_WORKFLOW_NAME: "Weekly Reference Implementation Sync Agentic Workflow" GH_AW_INFO_EXPERIMENTAL: "false" GH_AW_INFO_SUPPORTS_TOOLS_ALLOWLIST: "true" GH_AW_INFO_STAGED: "false" @@ -95,7 +95,7 @@ jobs: - name: Check workflow file timestamps uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: - GH_AW_WORKFLOW_FILE: "weekly-upstream-sync.lock.yml" + GH_AW_WORKFLOW_FILE: "weekly-reference-impl-sync.lock.yml" with: script: | const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs'); @@ -161,7 +161,7 @@ jobs: GH_AW_PROMPT_EOF cat << 'GH_AW_PROMPT_EOF' - {{#runtime-import .github/workflows/weekly-upstream-sync.md}} + {{#runtime-import .github/workflows/weekly-reference-impl-sync.md}} GH_AW_PROMPT_EOF } > "$GH_AW_PROMPT" - name: Interpolate variables and render templates @@ -243,7 +243,7 @@ jobs: GH_AW_SAFE_OUTPUTS: /opt/gh-aw/safeoutputs/outputs.jsonl GH_AW_SAFE_OUTPUTS_CONFIG_PATH: /opt/gh-aw/safeoutputs/config.json GH_AW_SAFE_OUTPUTS_TOOLS_PATH: /opt/gh-aw/safeoutputs/tools.json - GH_AW_WORKFLOW_ID_SANITIZED: weeklyupstreamsync + GH_AW_WORKFLOW_ID_SANITIZED: weeklyreferenceimplsync outputs: checkout_pr_success: ${{ steps.checkout-pr.outputs.checkout_pr_success || 'true' }} detection_conclusion: ${{ steps.detection_conclusion.outputs.conclusion }} @@ -311,12 +311,12 @@ jobs: mkdir -p /tmp/gh-aw/safeoutputs mkdir -p /tmp/gh-aw/mcp-logs/safeoutputs cat > /opt/gh-aw/safeoutputs/config.json << 'GH_AW_SAFE_OUTPUTS_CONFIG_EOF' - {"add_comment":{"max":10,"target":"*"},"assign_to_agent":{"default_agent":"copilot","max":1,"target":"*"},"close_issue":{"max":10,"required_labels":["upstream-sync"],"target":"*"},"create_issue":{"expires":144,"max":1},"missing_data":{},"missing_tool":{},"noop":{"max":1}} + {"add_comment":{"max":10,"target":"*"},"assign_to_agent":{"default_agent":"copilot","max":1,"target":"*"},"close_issue":{"max":10,"required_labels":["reference-impl-sync"],"target":"*"},"create_issue":{"expires":144,"max":1},"missing_data":{},"missing_tool":{},"noop":{"max":1}} GH_AW_SAFE_OUTPUTS_CONFIG_EOF cat > /opt/gh-aw/safeoutputs/tools.json << 'GH_AW_SAFE_OUTPUTS_TOOLS_EOF' [ { - "description": "Create a new GitHub issue for tracking bugs, feature requests, or tasks. Use this for actionable work items that need assignment, labeling, and status tracking. For reports, announcements, or status updates that don't require task tracking, use create_discussion instead. CONSTRAINTS: Maximum 1 issue(s) can be created. Title will be prefixed with \"[upstream-sync] \". Labels [upstream-sync] will be automatically added. Assignees [copilot] will be automatically assigned.", + "description": "Create a new GitHub issue for tracking bugs, feature requests, or tasks. Use this for actionable work items that need assignment, labeling, and status tracking. For reports, announcements, or status updates that don't require task tracking, use create_discussion instead. CONSTRAINTS: Maximum 1 issue(s) can be created. Title will be prefixed with \"[reference-impl-sync] \". Labels [reference-impl-sync] will be automatically added. Assignees [copilot] will be automatically assigned.", "inputSchema": { "additionalProperties": false, "properties": { @@ -958,8 +958,8 @@ jobs: if: always() && steps.detection_guard.outputs.run_detection == 'true' uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: - WORKFLOW_NAME: "Weekly Upstream Sync Agentic Workflow" - WORKFLOW_DESCRIPTION: "Weekly upstream sync workflow. Checks for new commits in the official\nCopilot SDK (github/copilot-sdk) and assigns to Copilot to port changes." + WORKFLOW_NAME: "Weekly Reference Implementation Sync Agentic Workflow" + WORKFLOW_DESCRIPTION: "Weekly reference implementation sync workflow. Checks for new commits in the official\nCopilot SDK (github/copilot-sdk) and assigns to Copilot to port changes." HAS_PATCH: ${{ steps.collect_output.outputs.has_patch }} with: script: | @@ -1077,7 +1077,7 @@ jobs: env: GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} GH_AW_NOOP_MAX: "1" - GH_AW_WORKFLOW_NAME: "Weekly Upstream Sync Agentic Workflow" + GH_AW_WORKFLOW_NAME: "Weekly Reference Implementation Sync Agentic Workflow" with: github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} script: | @@ -1090,7 +1090,7 @@ jobs: uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} - GH_AW_WORKFLOW_NAME: "Weekly Upstream Sync Agentic Workflow" + GH_AW_WORKFLOW_NAME: "Weekly Reference Implementation Sync Agentic Workflow" with: github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} script: | @@ -1103,10 +1103,10 @@ jobs: uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} - GH_AW_WORKFLOW_NAME: "Weekly Upstream Sync Agentic Workflow" + GH_AW_WORKFLOW_NAME: "Weekly Reference Implementation Sync Agentic Workflow" GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }} - GH_AW_WORKFLOW_ID: "weekly-upstream-sync" + GH_AW_WORKFLOW_ID: "weekly-reference-impl-sync" GH_AW_SECRET_VERIFICATION_RESULT: ${{ needs.activation.outputs.secret_verification_result }} GH_AW_CHECKOUT_PR_SUCCESS: ${{ needs.agent.outputs.checkout_pr_success }} GH_AW_ASSIGNMENT_ERRORS: ${{ needs.safe_outputs.outputs.assign_to_agent_assignment_errors }} @@ -1124,7 +1124,7 @@ jobs: uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: GH_AW_AGENT_OUTPUT: ${{ env.GH_AW_AGENT_OUTPUT }} - GH_AW_WORKFLOW_NAME: "Weekly Upstream Sync Agentic Workflow" + GH_AW_WORKFLOW_NAME: "Weekly Reference Implementation Sync Agentic Workflow" GH_AW_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} GH_AW_AGENT_CONCLUSION: ${{ needs.agent.result }} GH_AW_NOOP_MESSAGE: ${{ steps.noop.outputs.noop_message }} @@ -1150,8 +1150,8 @@ jobs: env: GH_AW_CALLER_WORKFLOW_ID: "${{ github.repository }}/${{ github.workflow }}" GH_AW_ENGINE_ID: "copilot" - GH_AW_WORKFLOW_ID: "weekly-upstream-sync" - GH_AW_WORKFLOW_NAME: "Weekly Upstream Sync Agentic Workflow" + GH_AW_WORKFLOW_ID: "weekly-reference-impl-sync" + GH_AW_WORKFLOW_NAME: "Weekly Reference Implementation Sync Agentic Workflow" outputs: assign_to_agent_assigned: ${{ steps.assign_to_agent.outputs.assigned }} assign_to_agent_assignment_error_count: ${{ steps.assign_to_agent.outputs.assignment_error_count }} @@ -1190,7 +1190,7 @@ jobs: GH_AW_ALLOWED_DOMAINS: "*.githubusercontent.com,api.business.githubcopilot.com,api.enterprise.githubcopilot.com,api.github.com,api.githubcopilot.com,api.individual.githubcopilot.com,api.snapcraft.io,archive.ubuntu.com,azure.archive.ubuntu.com,codeload.github.com,crl.geotrust.com,crl.globalsign.com,crl.identrust.com,crl.sectigo.com,crl.thawte.com,crl.usertrust.com,crl.verisign.com,crl3.digicert.com,crl4.digicert.com,crls.ssl.com,github-cloud.githubusercontent.com,github-cloud.s3.amazonaws.com,github.com,github.githubassets.com,host.docker.internal,json-schema.org,json.schemastore.org,keyserver.ubuntu.com,lfs.github.com,objects.githubusercontent.com,ocsp.digicert.com,ocsp.geotrust.com,ocsp.globalsign.com,ocsp.identrust.com,ocsp.sectigo.com,ocsp.ssl.com,ocsp.thawte.com,ocsp.usertrust.com,ocsp.verisign.com,packagecloud.io,packages.cloud.google.com,packages.microsoft.com,ppa.launchpad.net,raw.githubusercontent.com,registry.npmjs.org,s.symcb.com,s.symcd.com,security.ubuntu.com,telemetry.enterprise.githubcopilot.com,ts-crl.ws.symantec.com,ts-ocsp.ws.symantec.com" GITHUB_SERVER_URL: ${{ github.server_url }} GITHUB_API_URL: ${{ github.api_url }} - GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"max\":10,\"target\":\"*\"},\"close_issue\":{\"max\":10,\"required_labels\":[\"upstream-sync\"],\"target\":\"*\"},\"create_issue\":{\"assignees\":[\"copilot\"],\"expires\":144,\"labels\":[\"upstream-sync\"],\"max\":1,\"title_prefix\":\"[upstream-sync] \"},\"missing_data\":{},\"missing_tool\":{}}" + GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: "{\"add_comment\":{\"max\":10,\"target\":\"*\"},\"close_issue\":{\"max\":10,\"required_labels\":[\"reference-impl-sync\"],\"target\":\"*\"},\"create_issue\":{\"assignees\":[\"copilot\"],\"expires\":144,\"labels\":[\"reference-impl-sync\"],\"max\":1,\"title_prefix\":\"[reference-impl-sync] \"},\"missing_data\":{},\"missing_tool\":{}}" GH_AW_ASSIGN_COPILOT: "true" with: github-token: ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/weekly-reference-impl-sync.md b/.github/workflows/weekly-reference-impl-sync.md new file mode 100644 index 000000000..711f16ccb --- /dev/null +++ b/.github/workflows/weekly-reference-impl-sync.md @@ -0,0 +1,117 @@ +--- +description: | + Weekly reference implementation sync workflow. Checks for new commits in the official + Copilot SDK (github/copilot-sdk) and assigns to Copilot to port changes. + +on: + schedule: weekly + workflow_dispatch: + +permissions: + contents: read + actions: read + issues: read + +network: + allowed: + - defaults + - github + +tools: + github: + toolsets: [context, repos, issues] + +safe-outputs: + create-issue: + title-prefix: "[reference-impl-sync] " + assignees: [copilot] + labels: [reference-impl-sync] + expires: 6 + close-issue: + required-labels: [reference-impl-sync] + target: "*" + max: 10 + add-comment: + target: "*" + max: 10 + assign-to-agent: + name: "copilot" + model: "claude-opus-4.6" + target: "*" + noop: + report-as-issue: false +--- +# Weekly Reference Implementation Sync + +You are an automation agent that detects new reference implementation changes and creates GitHub issues. You do **NOT** perform any code merges, edits, or pushes. Do **NOT** invoke any skills (especially `agentic-merge-reference-impl`). Your only job is to check for changes and use safe-output tools to create or close issues. + +## Instructions + +Follow these steps exactly: + +### Step 1: Read `.lastmerge` + +Read the file `.lastmerge` in the repository root. It contains the SHA of the last reference implementation commit that was merged into this Java SDK. + +### Step 2: Check for reference implementation changes + +Clone the reference implementation repository and compare commits: + +```bash +LAST_MERGE=$(cat .lastmerge) +git clone --quiet https://github.com/github/copilot-sdk.git /tmp/gh-aw/agent/refererce-impl +cd /tmp/gh-aw/agent/refererce-impl +REFERENCE_IMPL_HEAD=$(git rev-parse HEAD) +``` + +If `LAST_MERGE` equals `REFERENCE_IMPL_HEAD`, there are **no new changes**. Go to Step 3a. + +If they differ, count the new commits and generate a summary: + +```bash +COMMIT_COUNT=$(git rev-list --count "$LAST_MERGE".."$REFERENCE_IMPL_HEAD") +SUMMARY=$(git log --oneline "$LAST_MERGE".."$REFERENCE_IMPL_HEAD" | head -20) +``` + +Go to Step 3b. + +### Step 3a: No changes detected + +1. Search for any open issues with the `reference-impl-sync` label using the GitHub MCP tools. +2. If there are open `reference-impl-sync` labeled issues, close each one using the `close_issue` safe-output tool with a comment: "No new reference implementation changes detected. The Java SDK is up to date. Closing." +3. Call the `noop` safe-output tool with message: "No new reference implementation changes since last merge ()." +4. **Stop here.** Do not proceed further. + +### Step 3b: Changes detected + +1. Search for any open issues with the `refererce-impl-sync` label using the GitHub MCP tools. +2. Close each existing open `refererce-impl-sync` issue using the `close_issue` safe-output tool with a comment: "Superseded by a newer reference implementation sync check." +3. Create a new issue using the `create_issue` safe-output tool with: + - **Title:** `Reference Implementation sync: new commits ()` + - **Body:** Include the following information: + ``` + ## Automated Reference Implementation Sync + + There are **** new commits in the [official Copilot SDK](https://github.com/github/copilot-sdk) since the last merge. + + - **Last merged commit:** [``](https://github.com/github/copilot-sdk/commit/) + - **Reference Implementation HEAD:** [``](https://github.com/github/copilot-sdk/commit/) + + ### Recent reference implementation commits + + ``` + + ``` + + ### Instructions + + Follow the [agentic-merge-reference-impl](.github/prompts/agentic-merge-reference-impl.prompt.md) prompt to port these changes to the Java SDK. + ``` +4. After creating the issue, use the `assign_to_agent` safe-output tool to assign Copilot to the newly created issue. + +## Important constraints + +- **Do NOT edit any files**, create branches, or push code. +- **Do NOT invoke any skills** such as `agentic-merge-agentic-merge-reference-impl` or `commit-as-pull-request`. +- **Do NOT attempt to merge or port reference implementation changes.** That is done by a separate agent that picks up the issue you create. +- You **MUST** call at least one safe-output tool (`create_issue`, `close_issue`, `noop`, etc.) before finishing. diff --git a/.github/workflows/weekly-upstream-sync.yml b/.github/workflows/weekly-reference-impl-sync.yml similarity index 66% rename from .github/workflows/weekly-upstream-sync.yml rename to .github/workflows/weekly-reference-impl-sync.yml index 5281fa032..aa3fc971a 100644 --- a/.github/workflows/weekly-upstream-sync.yml +++ b/.github/workflows/weekly-reference-impl-sync.yml @@ -1,4 +1,4 @@ -name: "Weekly Upstream Sync" +name: "Weekly Reference Implementation Sync" on: schedule: @@ -19,39 +19,39 @@ env: jobs: check-and-sync: - name: "Check upstream & trigger Copilot merge" + name: "Check reference implementation & trigger Copilot merge" runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Check for upstream changes + - name: Check for reference implementation changes id: check run: | LAST_MERGE=$(cat .lastmerge) echo "Last merged commit: $LAST_MERGE" - git clone --quiet https://github.com/github/copilot-sdk.git /tmp/upstream - cd /tmp/upstream + git clone --quiet https://github.com/github/copilot-sdk.git /tmp/reference-impl + cd /tmp/reference-impl - UPSTREAM_HEAD=$(git rev-parse HEAD) - echo "Upstream HEAD: $UPSTREAM_HEAD" + REFERENCE_IMPL_HEAD=$(git rev-parse HEAD) + echo "Reference implementation HEAD: $REFERENCE_IMPL_HEAD" echo "last_merge=$LAST_MERGE" >> "$GITHUB_OUTPUT" - if [ "$LAST_MERGE" = "$UPSTREAM_HEAD" ]; then - echo "No new upstream changes since last merge." + if [ "$LAST_MERGE" = "$REFERENCE_IMPL_HEAD" ]; then + echo "No new reference implementation changes since last merge." echo "has_changes=false" >> "$GITHUB_OUTPUT" else - COMMIT_COUNT=$(git rev-list --count "$LAST_MERGE".."$UPSTREAM_HEAD") - echo "Found $COMMIT_COUNT new upstream commits." + COMMIT_COUNT=$(git rev-list --count "$LAST_MERGE".."$REFERENCE_IMPL_HEAD") + echo "Found $COMMIT_COUNT new reference implementation commits." echo "has_changes=true" >> "$GITHUB_OUTPUT" echo "commit_count=$COMMIT_COUNT" >> "$GITHUB_OUTPUT" - echo "upstream_head=$UPSTREAM_HEAD" >> "$GITHUB_OUTPUT" + echo "reference_impl_head=$REFERENCE_IMPL_HEAD" >> "$GITHUB_OUTPUT" # Generate a short summary of changes - SUMMARY=$(git log --oneline "$LAST_MERGE".."$UPSTREAM_HEAD" | head -20) + SUMMARY=$(git log --oneline "$LAST_MERGE".."$REFERENCE_IMPL_HEAD" | head -20) { echo "summary<> "$GITHUB_OUTPUT" fi - - name: Close previous upstream-sync issues + - name: Close previous reference-impl-sync issues if: steps.check.outputs.has_changes == 'true' run: | - # Find all open issues with the upstream-sync label + # Find all open issues with the reference-impl-sync label OPEN_ISSUES=$(gh issue list \ --repo "${{ github.repository }}" \ - --label "upstream-sync" \ + --label "reference-impl-sync" \ --state open \ --json number \ --jq '.[].number') @@ -74,27 +74,27 @@ jobs: echo "Closing superseded issue #${ISSUE_NUM}" gh issue comment "$ISSUE_NUM" \ --repo "${{ github.repository }}" \ - --body "Superseded by a newer upstream sync issue. Closing this one." + --body "Superseded by a newer reference implementation sync issue. Closing this one." gh issue close "$ISSUE_NUM" \ --repo "${{ github.repository }}" \ --reason "not planned" done - - name: Close stale upstream-sync issues (no changes) + - name: Close stale reference-impl-sync issues (no changes) if: steps.check.outputs.has_changes == 'false' run: | OPEN_ISSUES=$(gh issue list \ --repo "${{ github.repository }}" \ - --label "upstream-sync" \ + --label "reference-impl-sync" \ --state open \ --json number \ --jq '.[].number') for ISSUE_NUM in $OPEN_ISSUES; do - echo "Closing stale issue #${ISSUE_NUM} — upstream is up to date" + echo "Closing stale issue #${ISSUE_NUM} — reference implementation is up to date" gh issue comment "$ISSUE_NUM" \ --repo "${{ github.repository }}" \ - --body "No new upstream changes detected. The Java SDK is up to date. Closing." + --body "No new reference implementation changes detected. The Java SDK is up to date. Closing." gh issue close "$ISSUE_NUM" \ --repo "${{ github.repository }}" \ --reason "completed" @@ -108,18 +108,18 @@ jobs: run: | COMMIT_COUNT="${{ steps.check.outputs.commit_count }}" LAST_MERGE="${{ steps.check.outputs.last_merge }}" - UPSTREAM_HEAD="${{ steps.check.outputs.upstream_head }}" + REFERENCE_IMPL_HEAD="${{ steps.check.outputs.reference_impl_head }}" DATE=$(date -u +"%Y-%m-%d") REPO="${{ github.repository }}" - BODY="## Automated Upstream Sync + BODY="## Automated Reference Implementation Sync There are **${COMMIT_COUNT}** new commits in the [official Copilot SDK](https://github.com/github/copilot-sdk) since the last merge. - **Last merged commit:** [\`${LAST_MERGE}\`](https://github.com/github/copilot-sdk/commit/${LAST_MERGE}) - - **Upstream HEAD:** [\`${UPSTREAM_HEAD}\`](https://github.com/github/copilot-sdk/commit/${UPSTREAM_HEAD}) + - **Reference implementation HEAD:** [\`${REFERENCE_IMPL_HEAD}\`](https://github.com/github/copilot-sdk/commit/${REFERENCE_IMPL_HEAD}) - ### Recent upstream commits + ### Recent reference implementation commits \`\`\` ${SUMMARY} @@ -127,14 +127,14 @@ jobs: ### Instructions - Follow the [agentic-merge-upstream](.github/prompts/agentic-merge-upstream.prompt.md) prompt to port these changes to the Java SDK." + Follow the [agentic-merge-reference-impl](.github/prompts/agentic-merge-reference-impl.prompt.md) prompt to port these changes to the Java SDK." # Create the issue and assign to Copilot coding agent ISSUE_URL=$(gh issue create \ --repo "$REPO" \ - --title "Upstream sync: ${COMMIT_COUNT} new commits (${DATE})" \ + --title "Reference implementation sync: ${COMMIT_COUNT} new commits (${DATE})" \ --body "$BODY" \ - --label "upstream-sync" \ + --label "reference-impl-sync" \ --assignee "copilot-swe-agent") echo "issue_url=$ISSUE_URL" >> "$GITHUB_OUTPUT" @@ -148,25 +148,25 @@ jobs: HAS_CHANGES="${{ steps.check.outputs.has_changes }}" COMMIT_COUNT="${{ steps.check.outputs.commit_count }}" LAST_MERGE="${{ steps.check.outputs.last_merge }}" - UPSTREAM_HEAD="${{ steps.check.outputs.upstream_head }}" + REFERENCE_IMPL_HEAD="${{ steps.check.outputs.reference_impl_head }}" ISSUE_URL="${{ steps.create-issue.outputs.issue_url }}" { - echo "## Weekly Upstream Sync" + echo "## Weekly Reference Implementation Sync" echo "" if [ "$HAS_CHANGES" = "true" ]; then - echo "### ✅ New upstream changes detected" + echo "### ✅ New reference implementation changes detected" echo "" echo "| | |" echo "|---|---|" echo "| **New commits** | ${COMMIT_COUNT} |" echo "| **Last merged** | \`${LAST_MERGE:0:12}\` |" - echo "| **Upstream HEAD** | \`${UPSTREAM_HEAD:0:12}\` |" + echo "| **Reference implementation HEAD** | \`${REFERENCE_IMPL_HEAD:0:12}\` |" echo "" echo "An issue has been created and assigned to the Copilot coding agent: " echo " -> ${ISSUE_URL}" echo "" - echo "### Recent upstream commits" + echo "### Recent reference implementation commits" echo "" echo '```' echo "$SUMMARY" @@ -174,7 +174,7 @@ jobs: else echo "### ⏭️ No changes" echo "" - echo "The Java SDK is already up to date with the upstream Copilot SDK." + echo "The Java SDK is already up to date with the reference implementation Copilot SDK." echo "" echo "**Last merged commit:** \`${LAST_MERGE:0:12}\`" fi diff --git a/.github/workflows/weekly-upstream-sync.md b/.github/workflows/weekly-upstream-sync.md deleted file mode 100644 index 0aaff8d1e..000000000 --- a/.github/workflows/weekly-upstream-sync.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -description: | - Weekly upstream sync workflow. Checks for new commits in the official - Copilot SDK (github/copilot-sdk) and assigns to Copilot to port changes. - -on: - schedule: weekly - workflow_dispatch: - -permissions: - contents: read - actions: read - issues: read - -network: - allowed: - - defaults - - github - -tools: - github: - toolsets: [context, repos, issues] - -safe-outputs: - create-issue: - title-prefix: "[upstream-sync] " - assignees: [copilot] - labels: [upstream-sync] - expires: 6 - close-issue: - required-labels: [upstream-sync] - target: "*" - max: 10 - add-comment: - target: "*" - max: 10 - assign-to-agent: - name: "copilot" - model: "claude-opus-4.6" - target: "*" - noop: - report-as-issue: false ---- -# Weekly Upstream Sync - -You are an automation agent that detects new upstream changes and creates GitHub issues. You do **NOT** perform any code merges, edits, or pushes. Do **NOT** invoke any skills (especially `agentic-merge-upstream`). Your only job is to check for changes and use safe-output tools to create or close issues. - -## Instructions - -Follow these steps exactly: - -### Step 1: Read `.lastmerge` - -Read the file `.lastmerge` in the repository root. It contains the SHA of the last upstream commit that was merged into this Java SDK. - -### Step 2: Check for upstream changes - -Clone the upstream repository and compare commits: - -```bash -LAST_MERGE=$(cat .lastmerge) -git clone --quiet https://github.com/github/copilot-sdk.git /tmp/gh-aw/agent/upstream -cd /tmp/gh-aw/agent/upstream -UPSTREAM_HEAD=$(git rev-parse HEAD) -``` - -If `LAST_MERGE` equals `UPSTREAM_HEAD`, there are **no new changes**. Go to Step 3a. - -If they differ, count the new commits and generate a summary: - -```bash -COMMIT_COUNT=$(git rev-list --count "$LAST_MERGE".."$UPSTREAM_HEAD") -SUMMARY=$(git log --oneline "$LAST_MERGE".."$UPSTREAM_HEAD" | head -20) -``` - -Go to Step 3b. - -### Step 3a: No changes detected - -1. Search for any open issues with the `upstream-sync` label using the GitHub MCP tools. -2. If there are open `upstream-sync` issues, close each one using the `close_issue` safe-output tool with a comment: "No new upstream changes detected. The Java SDK is up to date. Closing." -3. Call the `noop` safe-output tool with message: "No new upstream changes since last merge ()." -4. **Stop here.** Do not proceed further. - -### Step 3b: Changes detected - -1. Search for any open issues with the `upstream-sync` label using the GitHub MCP tools. -2. Close each existing open `upstream-sync` issue using the `close_issue` safe-output tool with a comment: "Superseded by a newer upstream sync check." -3. Create a new issue using the `create_issue` safe-output tool with: - - **Title:** `Upstream sync: new commits ()` - - **Body:** Include the following information: - ``` - ## Automated Upstream Sync - - There are **** new commits in the [official Copilot SDK](https://github.com/github/copilot-sdk) since the last merge. - - - **Last merged commit:** [``](https://github.com/github/copilot-sdk/commit/) - - **Upstream HEAD:** [``](https://github.com/github/copilot-sdk/commit/) - - ### Recent upstream commits - - ``` - - ``` - - ### Instructions - - Follow the [agentic-merge-upstream](.github/prompts/agentic-merge-upstream.prompt.md) prompt to port these changes to the Java SDK. - ``` -4. After creating the issue, use the `assign_to_agent` safe-output tool to assign Copilot to the newly created issue. - -## Important constraints - -- **Do NOT edit any files**, create branches, or push code. -- **Do NOT invoke any skills** such as `agentic-merge-upstream` or `commit-as-pull-request`. -- **Do NOT attempt to merge or port upstream changes.** That is done by a separate agent that picks up the issue you create. -- You **MUST** call at least one safe-output tool (`create_issue`, `close_issue`, `noop`, etc.) before finishing. diff --git a/.gitignore b/.gitignore index ddb2508ba..f079a3d20 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ changebundle.txt* .classpath .project .settings +*~ diff --git a/CHANGELOG.md b/CHANGELOG.md index 38f6e6589..130bc5105 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,17 +8,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] -> **Upstream sync:** [`github/copilot-sdk@c3fa6cb`](https://github.com/github/copilot-sdk/commit/c3fa6cbfb83d4a20b7912b1a17013d48f5a277a1) +> **Reference implementation sync:** [`github/copilot-sdk@c3fa6cb`](https://github.com/github/copilot-sdk/commit/c3fa6cbfb83d4a20b7912b1a17013d48f5a277a1) ## [0.2.2-java.1] - 2026-04-07 -> **Upstream sync:** [`github/copilot-sdk@c3fa6cb`](https://github.com/github/copilot-sdk/commit/c3fa6cbfb83d4a20b7912b1a17013d48f5a277a1) +> **Reference implementation sync:** [`github/copilot-sdk@c3fa6cb`](https://github.com/github/copilot-sdk/commit/c3fa6cbfb83d4a20b7912b1a17013d48f5a277a1) ### Added -- Slash commands — register `/command` handlers invoked from the CLI TUI via `SessionConfig.setCommands()` (upstream: [`f7fd757`](https://github.com/github/copilot-sdk/commit/f7fd757)) +- Slash commands — register `/command` handlers invoked from the CLI TUI via `SessionConfig.setCommands()` (reference implementation: [`f7fd757`](https://github.com/github/copilot-sdk/commit/f7fd757)) - `CommandDefinition`, `CommandContext`, `CommandHandler`, `CommandWireDefinition` — types for defining and handling slash commands - `CommandExecuteEvent` — event dispatched when a registered slash command is executed -- Elicitation (UI dialogs) — incoming handler via `SessionConfig.setOnElicitationRequest()` and outgoing convenience methods via `session.getUi()` (upstream: [`f7fd757`](https://github.com/github/copilot-sdk/commit/f7fd757)) +- Elicitation (UI dialogs) — incoming handler via `SessionConfig.setOnElicitationRequest()` and outgoing convenience methods via `session.getUi()` (reference implementation: [`f7fd757`](https://github.com/github/copilot-sdk/commit/f7fd757)) - `ElicitationContext`, `ElicitationHandler`, `ElicitationParams`, `ElicitationResult`, `ElicitationResultAction`, `ElicitationSchema`, `InputOptions` — types for elicitation - `ElicitationRequestedEvent` — event dispatched when an elicitation request is received - `SessionUiApi` — convenience API on `session.getUi()` for `confirm()`, `select()`, `input()`, and `elicitation()` calls @@ -35,27 +35,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [0.2.1-java.1] - 2026-04-02 -> **Upstream sync:** [`github/copilot-sdk@4088739`](https://github.com/github/copilot-sdk/commit/40887393a9e687dacc141a645799441b0313ff15) +> **Reference implementation sync:** [`github/copilot-sdk@4088739`](https://github.com/github/copilot-sdk/commit/40887393a9e687dacc141a645799441b0313ff15) ## [0.2.1-java.0] - 2026-03-26 -> **Upstream sync:** [`github/copilot-sdk@4088739`](https://github.com/github/copilot-sdk/commit/40887393a9e687dacc141a645799441b0313ff15) +> **Reference implementation sync:** [`github/copilot-sdk@4088739`](https://github.com/github/copilot-sdk/commit/40887393a9e687dacc141a645799441b0313ff15) ### Added -- `UnknownSessionEvent` — forward-compatible placeholder for event types not yet known to the SDK; unknown events are now dispatched to handlers instead of being silently dropped (upstream: [`d82fd62`](https://github.com/github/copilot-sdk/commit/d82fd62)) -- `PermissionRequestResultKind.NO_RESULT` — new constant that signals the handler intentionally abstains from answering a permission request, leaving it unanswered for another client (upstream: [`df59a0e`](https://github.com/github/copilot-sdk/commit/df59a0e)) -- `ToolDefinition.skipPermission` field and `ToolDefinition.createSkipPermission()` factory — marks a tool to skip the permission prompt (upstream: [`10c4d02`](https://github.com/github/copilot-sdk/commit/10c4d02)) -- `SystemMessageMode.CUSTOMIZE` — new enum value for fine-grained system prompt customization (upstream: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) -- `SectionOverrideAction` enum — specifies the operation on a system prompt section (replace, remove, append, prepend, transform) (upstream: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) -- `SectionOverride` class — describes how one section of the system prompt should be modified, with optional transform callback (upstream: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) -- `SystemPromptSections` constants — well-known section identifier strings for use with CUSTOMIZE mode (upstream: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) -- `SystemMessageConfig.setSections(Map)` — section-level overrides for CUSTOMIZE mode (upstream: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) -- `systemMessage.transform` RPC handler — the SDK now registers a handler that invokes transform callbacks registered in the session config (upstream: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) -- `CopilotSession.setModel(String, String)` — new overload that accepts an optional reasoning effort level (upstream: [`ea90f07`](https://github.com/github/copilot-sdk/commit/ea90f07)) +- `UnknownSessionEvent` — forward-compatible placeholder for event types not yet known to the SDK; unknown events are now dispatched to handlers instead of being silently dropped (reference implementation: [`d82fd62`](https://github.com/github/copilot-sdk/commit/d82fd62)) +- `PermissionRequestResultKind.NO_RESULT` — new constant that signals the handler intentionally abstains from answering a permission request, leaving it unanswered for another client (reference implementation: [`df59a0e`](https://github.com/github/copilot-sdk/commit/df59a0e)) +- `ToolDefinition.skipPermission` field and `ToolDefinition.createSkipPermission()` factory — marks a tool to skip the permission prompt (reference implementation: [`10c4d02`](https://github.com/github/copilot-sdk/commit/10c4d02)) +- `SystemMessageMode.CUSTOMIZE` — new enum value for fine-grained system prompt customization (reference implementation: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) +- `SectionOverrideAction` enum — specifies the operation on a system prompt section (replace, remove, append, prepend, transform) (reference implementation: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) +- `SectionOverride` class — describes how one section of the system prompt should be modified, with optional transform callback (reference implementation: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) +- `SystemPromptSections` constants — well-known section identifier strings for use with CUSTOMIZE mode (reference implementation: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) +- `SystemMessageConfig.setSections(Map)` — section-level overrides for CUSTOMIZE mode (reference implementation: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) +- `systemMessage.transform` RPC handler — the SDK now registers a handler that invokes transform callbacks registered in the session config (reference implementation: [`005b780`](https://github.com/github/copilot-sdk/commit/005b780)) +- `CopilotSession.setModel(String, String)` — new overload that accepts an optional reasoning effort level (reference implementation: [`ea90f07`](https://github.com/github/copilot-sdk/commit/ea90f07)) - `CopilotSession.log(String, String, Boolean, String)` — new overload with an optional `url` parameter (minor addition) -- `BlobAttachment` class — inline base64-encoded binary attachment for messages (e.g., images) (upstream: [`698b259`](https://github.com/github/copilot-sdk/commit/698b259)) +- `BlobAttachment` class — inline base64-encoded binary attachment for messages (e.g., images) (reference implementation: [`698b259`](https://github.com/github/copilot-sdk/commit/698b259)) - `MessageAttachment` sealed interface — type-safe base for all attachment types (`Attachment`, `BlobAttachment`), with Jackson polymorphic serialization support -- `TelemetryConfig` class — OpenTelemetry configuration for the CLI server; set on `CopilotClientOptions.setTelemetry()` (upstream: [`f2d21a0`](https://github.com/github/copilot-sdk/commit/f2d21a0)) -- `CopilotClientOptions.setTelemetry(TelemetryConfig)` — enables OpenTelemetry instrumentation in the CLI server (upstream: [`f2d21a0`](https://github.com/github/copilot-sdk/commit/f2d21a0)) +- `TelemetryConfig` class — OpenTelemetry configuration for the CLI server; set on `CopilotClientOptions.setTelemetry()` (reference implementation: [`f2d21a0`](https://github.com/github/copilot-sdk/commit/f2d21a0)) +- `CopilotClientOptions.setTelemetry(TelemetryConfig)` — enables OpenTelemetry instrumentation in the CLI server (reference implementation: [`f2d21a0`](https://github.com/github/copilot-sdk/commit/f2d21a0)) ### Changed @@ -70,61 +70,61 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [0.1.32-java.0] - 2026-03-17 -> **Upstream sync:** [`github/copilot-sdk@062b61c`](https://github.com/github/copilot-sdk/commit/062b61c8aa63b9b5d45fa1d7b01723e6660ffa83) +> **Reference implementation sync:** [`github/copilot-sdk@062b61c`](https://github.com/github/copilot-sdk/commit/062b61c8aa63b9b5d45fa1d7b01723e6660ffa83) ## [1.0.11] - 2026-03-12 -> **Upstream sync:** [`github/copilot-sdk@062b61c`](https://github.com/github/copilot-sdk/commit/062b61c8aa63b9b5d45fa1d7b01723e6660ffa83) +> **Reference implementation sync:** [`github/copilot-sdk@062b61c`](https://github.com/github/copilot-sdk/commit/062b61c8aa63b9b5d45fa1d7b01723e6660ffa83) ### Added -- `CopilotClientOptions.setOnListModels(Supplier>>)` — custom handler for `listModels()` used in BYOK mode to return models from a custom provider instead of querying the CLI (upstream: [`e478657`](https://github.com/github/copilot-sdk/commit/e478657)) -- `SessionConfig.setAgent(String)` — pre-selects a custom agent by name when creating a session (upstream: [`7766b1a`](https://github.com/github/copilot-sdk/commit/7766b1a)) -- `ResumeSessionConfig.setAgent(String)` — pre-selects a custom agent by name when resuming a session (upstream: [`7766b1a`](https://github.com/github/copilot-sdk/commit/7766b1a)) -- `SessionConfig.setOnEvent(Consumer)` — registers an event handler before the `session.create` RPC is issued, ensuring no early events are missed (upstream: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7)) -- `ResumeSessionConfig.setOnEvent(Consumer)` — registers an event handler before the `session.resume` RPC is issued (upstream: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7)) -- New broadcast session event types (protocol v3): `ExternalToolRequestedEvent` (`external_tool.requested`), `ExternalToolCompletedEvent` (`external_tool.completed`), `PermissionRequestedEvent` (`permission.requested`), `PermissionCompletedEvent` (`permission.completed`), `CommandQueuedEvent` (`command.queued`), `CommandCompletedEvent` (`command.completed`), `ExitPlanModeRequestedEvent` (`exit_plan_mode.requested`), `ExitPlanModeCompletedEvent` (`exit_plan_mode.completed`), `SystemNotificationEvent` (`system.notification`) (upstream: [`1653812`](https://github.com/github/copilot-sdk/commit/1653812), [`396e8b3`](https://github.com/github/copilot-sdk/commit/396e8b3)) -- `CopilotSession.log(String)` and `CopilotSession.log(String, String, Boolean)` — log a message to the session timeline (upstream: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7)) +- `CopilotClientOptions.setOnListModels(Supplier>>)` — custom handler for `listModels()` used in BYOK mode to return models from a custom provider instead of querying the CLI (reference implementation: [`e478657`](https://github.com/github/copilot-sdk/commit/e478657)) +- `SessionConfig.setAgent(String)` — pre-selects a custom agent by name when creating a session (reference implementation: [`7766b1a`](https://github.com/github/copilot-sdk/commit/7766b1a)) +- `ResumeSessionConfig.setAgent(String)` — pre-selects a custom agent by name when resuming a session (reference implementation: [`7766b1a`](https://github.com/github/copilot-sdk/commit/7766b1a)) +- `SessionConfig.setOnEvent(Consumer)` — registers an event handler before the `session.create` RPC is issued, ensuring no early events are missed (reference implementation: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7)) +- `ResumeSessionConfig.setOnEvent(Consumer)` — registers an event handler before the `session.resume` RPC is issued (reference implementation: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7)) +- New broadcast session event types (protocol v3): `ExternalToolRequestedEvent` (`external_tool.requested`), `ExternalToolCompletedEvent` (`external_tool.completed`), `PermissionRequestedEvent` (`permission.requested`), `PermissionCompletedEvent` (`permission.completed`), `CommandQueuedEvent` (`command.queued`), `CommandCompletedEvent` (`command.completed`), `ExitPlanModeRequestedEvent` (`exit_plan_mode.requested`), `ExitPlanModeCompletedEvent` (`exit_plan_mode.completed`), `SystemNotificationEvent` (`system.notification`) (reference implementation: [`1653812`](https://github.com/github/copilot-sdk/commit/1653812), [`396e8b3`](https://github.com/github/copilot-sdk/commit/396e8b3)) +- `CopilotSession.log(String)` and `CopilotSession.log(String, String, Boolean)` — log a message to the session timeline (reference implementation: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7)) ### Changed -- **Protocol version bumped to v3.** The SDK now supports CLI servers running v2 or v3 (backward-compatible range). Sessions are now registered in the client's session map *before* the `session.create`/`session.resume` RPC is issued, ensuring broadcast events emitted immediately on session start are never dropped (upstream: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7), [`1653812`](https://github.com/github/copilot-sdk/commit/1653812)) -- In protocol v3, tool calls and permission requests that have a registered handler are now handled automatically via `ExternalToolRequestedEvent` and `PermissionRequestedEvent` broadcast events; results are sent back via `session.tools.handlePendingToolCall` and `session.permissions.handlePendingPermissionRequest` RPC calls (upstream: [`1653812`](https://github.com/github/copilot-sdk/commit/1653812)) +- **Protocol version bumped to v3.** The SDK now supports CLI servers running v2 or v3 (backward-compatible range). Sessions are now registered in the client's session map *before* the `session.create`/`session.resume` RPC is issued, ensuring broadcast events emitted immediately on session start are never dropped (reference implementation: [`4125fe7`](https://github.com/github/copilot-sdk/commit/4125fe7), [`1653812`](https://github.com/github/copilot-sdk/commit/1653812)) +- In protocol v3, tool calls and permission requests that have a registered handler are now handled automatically via `ExternalToolRequestedEvent` and `PermissionRequestedEvent` broadcast events; results are sent back via `session.tools.handlePendingToolCall` and `session.permissions.handlePendingPermissionRequest` RPC calls (reference implementation: [`1653812`](https://github.com/github/copilot-sdk/commit/1653812)) ## [1.0.10] - 2026-03-03 -> **Upstream sync:** [`github/copilot-sdk@dcd86c1`](https://github.com/github/copilot-sdk/commit/dcd86c189501ce1b46b787ca60d90f3f315f3079) +> **Reference implementation sync:** [`github/copilot-sdk@dcd86c1`](https://github.com/github/copilot-sdk/commit/dcd86c189501ce1b46b787ca60d90f3f315f3079) ### Added -- `CopilotSession.setModel(String)` — changes the model for an existing session mid-conversation; the new model takes effect for the next message, and conversation history is preserved (upstream: [`bd98e3a`](https://github.com/github/copilot-sdk/commit/bd98e3a)) -- `ToolDefinition.createOverride(String, String, Map, ToolHandler)` — creates a tool definition that overrides a built-in CLI tool with the same name (upstream: [`f843c80`](https://github.com/github/copilot-sdk/commit/f843c80)) -- `ToolDefinition` record now includes `overridesBuiltInTool` field; when `true`, signals to the CLI that the custom tool intentionally replaces a built-in (upstream: [`f843c80`](https://github.com/github/copilot-sdk/commit/f843c80)) -- `CopilotSession.listAgents()` — lists custom agents available for selection (upstream: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) -- `CopilotSession.getCurrentAgent()` — gets the currently selected custom agent (upstream: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) -- `CopilotSession.selectAgent(String)` — selects a custom agent for the session (upstream: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) -- `CopilotSession.deselectAgent()` — deselects the current custom agent (upstream: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) -- `CopilotSession.compact()` — triggers immediate session context compaction (upstream: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) -- `AgentInfo` — new JSON type representing a custom agent with `name`, `displayName`, and `description` (upstream: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) -- New event types: `SessionTaskCompleteEvent` (`session.task_complete`), `AssistantStreamingDeltaEvent` (`assistant.streaming_delta`), `SubagentDeselectedEvent` (`subagent.deselected`) (upstream: various commits) +- `CopilotSession.setModel(String)` — changes the model for an existing session mid-conversation; the new model takes effect for the next message, and conversation history is preserved (reference implementation: [`bd98e3a`](https://github.com/github/copilot-sdk/commit/bd98e3a)) +- `ToolDefinition.createOverride(String, String, Map, ToolHandler)` — creates a tool definition that overrides a built-in CLI tool with the same name (reference implementation: [`f843c80`](https://github.com/github/copilot-sdk/commit/f843c80)) +- `ToolDefinition` record now includes `overridesBuiltInTool` field; when `true`, signals to the CLI that the custom tool intentionally replaces a built-in (reference implementation: [`f843c80`](https://github.com/github/copilot-sdk/commit/f843c80)) +- `CopilotSession.listAgents()` — lists custom agents available for selection (reference implementation: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) +- `CopilotSession.getCurrentAgent()` — gets the currently selected custom agent (reference implementation: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) +- `CopilotSession.selectAgent(String)` — selects a custom agent for the session (reference implementation: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) +- `CopilotSession.deselectAgent()` — deselects the current custom agent (reference implementation: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) +- `CopilotSession.compact()` — triggers immediate session context compaction (reference implementation: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) +- `AgentInfo` — new JSON type representing a custom agent with `name`, `displayName`, and `description` (reference implementation: [`9d998fb`](https://github.com/github/copilot-sdk/commit/9d998fb)) +- New event types: `SessionTaskCompleteEvent` (`session.task_complete`), `AssistantStreamingDeltaEvent` (`assistant.streaming_delta`), `SubagentDeselectedEvent` (`subagent.deselected`) (reference implementation: various commits) - `AssistantTurnStartEvent` data now includes `interactionId` field - `AssistantMessageEvent` data now includes `interactionId` field - `ToolExecutionCompleteEvent` data now includes `model` and `interactionId` fields - `SkillInvokedEvent` data now includes `pluginName` and `pluginVersion` fields - `AssistantUsageEvent` data now includes `copilotUsage` field with `CopilotUsage` and `TokenDetails` nested types -- E2E tests for custom tool permission approval and denial flows (upstream: [`388f2f3`](https://github.com/github/copilot-sdk/commit/388f2f3)) +- E2E tests for custom tool permission approval and denial flows (reference implementation: [`388f2f3`](https://github.com/github/copilot-sdk/commit/388f2f3)) ### Changed -- **Breaking:** `createSession(SessionConfig)` now requires a non-null `onPermissionRequest` handler; throws `IllegalArgumentException` if not provided (upstream: [`279f6c4`](https://github.com/github/copilot-sdk/commit/279f6c4)) -- **Breaking:** `resumeSession(String, ResumeSessionConfig)` now requires a non-null `onPermissionRequest` handler; throws `IllegalArgumentException` if not provided (upstream: [`279f6c4`](https://github.com/github/copilot-sdk/commit/279f6c4)) -- **Breaking:** The no-arg `createSession()` and `resumeSession(String)` overloads were removed (upstream: [`279f6c4`](https://github.com/github/copilot-sdk/commit/279f6c4)) -- `AssistantMessageDeltaEvent` data: `totalResponseSizeBytes` field moved to new `AssistantStreamingDeltaEvent` (upstream: various) +- **Breaking:** `createSession(SessionConfig)` now requires a non-null `onPermissionRequest` handler; throws `IllegalArgumentException` if not provided (reference implementation: [`279f6c4`](https://github.com/github/copilot-sdk/commit/279f6c4)) +- **Breaking:** `resumeSession(String, ResumeSessionConfig)` now requires a non-null `onPermissionRequest` handler; throws `IllegalArgumentException` if not provided (reference implementation: [`279f6c4`](https://github.com/github/copilot-sdk/commit/279f6c4)) +- **Breaking:** The no-arg `createSession()` and `resumeSession(String)` overloads were removed (reference implementation: [`279f6c4`](https://github.com/github/copilot-sdk/commit/279f6c4)) +- `AssistantMessageDeltaEvent` data: `totalResponseSizeBytes` field moved to new `AssistantStreamingDeltaEvent` (reference implementation: various) ### Fixed -- Permission checks now also apply to SDK-registered custom tools, invoking the `onPermissionRequest` handler with `kind="custom-tool"` before executing tools (upstream: [`388f2f3`](https://github.com/github/copilot-sdk/commit/388f2f3)) +- Permission checks now also apply to SDK-registered custom tools, invoking the `onPermissionRequest` handler with `kind="custom-tool"` before executing tools (reference implementation: [`388f2f3`](https://github.com/github/copilot-sdk/commit/388f2f3)) ## [1.0.9] - 2026-02-16 -> **Upstream sync:** [`github/copilot-sdk@e40d57c`](https://github.com/github/copilot-sdk/commit/e40d57c86e18b495722adbf42045288c03924342) +> **Reference implementation sync:** [`github/copilot-sdk@e40d57c`](https://github.com/github/copilot-sdk/commit/e40d57c86e18b495722adbf42045288c03924342) ### Added #### Cookbook with Practical Recipes @@ -191,7 +191,7 @@ session.on(SessionContextChangedEvent.class, event -> { ## [1.0.8] - 2026-02-08 -> **Upstream sync:** [`github/copilot-sdk@05e3c46`](https://github.com/github/copilot-sdk/commit/05e3c46c8c23130c9c064dc43d00ec78f7a75eab) +> **Reference implementation sync:** [`github/copilot-sdk@05e3c46`](https://github.com/github/copilot-sdk/commit/05e3c46c8c23130c9c064dc43d00ec78f7a75eab) ### Added @@ -347,7 +347,7 @@ New types: `GetForegroundSessionResponse`, `SetForegroundSessionResponse` ### Changed - Enhanced permission request handling with graceful error recovery -- Updated test harness integration to clone from upstream SDK +- Updated test harness integration to clone from reference implementation SDK - Improved logging for session events and user input requests ### Fixed @@ -366,8 +366,8 @@ New types: `GetForegroundSessionResponse`, `SetForegroundSessionResponse` ### Changed -- Merged upstream SDK changes (commit 87ff5510) -- Added agentic-merge-upstream Claude skill for tracking upstream changes +- Merged reference implementation SDK changes (commit 87ff5510) +- Added agentic-merge-reference-impl Claude skill for tracking reference implementation changes ### Fixed @@ -376,7 +376,7 @@ New types: `GetForegroundSessionResponse`, `SetForegroundSessionResponse` - NPM dependency installation in CI workflow - Enhanced error handling in permission request processing - Checkstyle and Maven Resources Plugin version updates -- Test harness CLI installation to match upstream version +- Test harness CLI installation to match reference implementation version ## [1.0.4] - 2026-01-27 @@ -394,7 +394,7 @@ New types: `GetForegroundSessionResponse`, `SetForegroundSessionResponse` - Refactored tool argument handling for improved type safety - Optimized event listener registration in examples - Enhanced site navigation with documentation links -- Merged upstream SDK changes from commit f902b76 +- Merged reference implementation SDK changes from commit f902b76 ### Fixed @@ -410,7 +410,7 @@ New types: `GetForegroundSessionResponse`, `SetForegroundSessionResponse` - MCP Servers documentation and integration examples - Infinite sessions documentation section - Versioned documentation template with version selector -- Guidelines for porting upstream SDK changes to Java +- Guidelines for porting reference implementation SDK changes to Java - Configuration for automatically generated release notes ### Changed @@ -519,3 +519,4 @@ New types: `GetForegroundSessionResponse`, `SetForegroundSessionResponse` [1.0.2]: https://github.com/github/copilot-sdk-java/compare/v1.0.1...v1.0.2 [1.0.1]: https://github.com/github/copilot-sdk-java/compare/1.0.0...v1.0.1 [1.0.0]: https://github.com/github/copilot-sdk-java/releases/tag/1.0.0 + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9320ee1a..f86976c01 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. -This repository contains the **GitHub Copilot SDK for Java**, the official Java variant of the official [GitHub Copilot SDK](https://github.com/github/copilot-sdk). For issues or features related to the upstream SDK, please contribute there instead. +This repository contains the **GitHub Copilot SDK for Java**, the official Java variant of the official [GitHub Copilot SDK](https://github.com/github/copilot-sdk). For issues or features related to the reference implementation SDK, please contribute there instead. Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE). @@ -19,7 +19,7 @@ We'd love your help with: * Making the SDK more idiomatic and nice to use for Java developers * Improving documentation -If you have ideas for entirely new features, please post an issue or start a discussion. We're very open to new features but need to make sure they align with the direction of the upstream [Copilot SDK](https://github.com/github/copilot-sdk) and can be maintained in sync. Note that this repo periodically merges upstream changes — see the [README](README.md#agentic-upstream-merge-and-sync) for details on how that works. +If you have ideas for entirely new features, please post an issue or start a discussion. We're very open to new features but need to make sure they align with the direction of the [Copilot SDK](https://github.com/github/copilot-sdk) reference implementation and can be maintained in sync. Note that this repo periodically merges reference implementation changes — see the [README](README.md#agentic-reference-implementation-merge-and-sync) for details on how that works. ## Prerequisites for running and testing code @@ -65,3 +65,4 @@ Here are a few things you can do that will increase the likelihood of your pull - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) - [GitHub Help](https://help.github.com) + diff --git a/README.md b/README.md index a33aaedda..d425fa4eb 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ jbang https://github.com/github/copilot-sdk-java/blob/latest/jbang-example.java ## CI/CD Workflows -This project uses several GitHub Actions workflows for building, testing, releasing, and syncing with the upstream SDK. +This project uses several GitHub Actions workflows for building, testing, releasing, and syncing with the reference implementation SDK. See [WORKFLOWS.md](docs/WORKFLOWS.md) for a full overview and details on each workflow. @@ -161,14 +161,14 @@ See [WORKFLOWS.md](docs/WORKFLOWS.md) for a full overview and details on each wo Contributions are welcome! Please see the [Contributing Guide](CONTRIBUTING.md) for details. -### Agentic Upstream Merge and Sync +### Agentic Reference Implementation Merge and Sync -This SDK tracks the official [Copilot SDK](https://github.com/github/copilot-sdk) (.NET reference implementation) and ports changes to Java. The upstream merge process is automated with AI assistance: +This SDK tracks the official [Copilot SDK](https://github.com/github/copilot-sdk) (.NET reference implementation) and ports changes to Java. The reference implementation merge process is automated with AI assistance: -**Weekly automated sync** — A [scheduled GitHub Actions workflow](.github/workflows/weekly-upstream-sync.yml) runs every Monday at 5 AM ET. It checks for new upstream commits since the last merge (tracked in [`.lastmerge`](.lastmerge)), and if changes are found, creates an issue labeled `upstream-sync` and assigns it to the GitHub Copilot coding agent. Any previously open `upstream-sync` issues are automatically closed. +**Weekly automated sync** — A [scheduled GitHub Actions workflow](.github/workflows/weekly-reference-impl-sync.yml) runs every Monday at 5 AM ET. It checks for new reference implementation commits since the last merge (tracked in [`.lastmerge`](.lastmerge)), and if changes are found, creates an issue labeled `reference-impl-sync` and assigns it to the GitHub Copilot coding agent. Any previously open `reference-impl-sync` issues are automatically closed. -**Reusable prompt** — The merge workflow is defined in [`agentic-merge-upstream.prompt.md`](.github/prompts/agentic-merge-upstream.prompt.md). It can be triggered manually from: -- **VS Code Copilot Chat** — type `/agentic-merge-upstream` +**Reusable prompt** — The merge workflow is defined in [`agentic-merge-reference-impl.prompt.md`](.github/prompts/agentic-merge-reference-impl.prompt.md). It can be triggered manually from: +- **VS Code Copilot Chat** — type `/agentic-merge-reference-impl` - **GitHub Copilot CLI** — use `copilot` CLI with the same skill reference ### Development Setup @@ -212,3 +212,4 @@ MIT — see [LICENSE](LICENSE) for details. [![Star History Chart](https://api.star-history.com/svg?repos=github/copilot-sdk-java&type=Date)](https://www.star-history.com/#github/copilot-sdk-java&Date) ⭐ Drop a star if you find this useful! + diff --git a/docs/WORKFLOWS.md b/docs/WORKFLOWS.md index 74afbd337..1cbb22b36 100644 --- a/docs/WORKFLOWS.md +++ b/docs/WORKFLOWS.md @@ -7,8 +7,8 @@ | [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 | | [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 Upstream Sync](workflows/weekly-upstream-sync.yml) | Checks for new upstream commits and creates an issue for Copilot to merge | `workflow_dispatch` | Mondays at 10:00 UTC | -| [Weekly Upstream Sync (Agentic)](workflows/weekly-upstream-sync.lock.yml) | Compiled agentic workflow that executes the upstream sync via `gh-aw` | `workflow_dispatch` | Tuesdays at 08:39 UTC (scattered) | +| [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 | +| [Weekly Reference Implementation Sync (Agentic)](workflows/weekly-reference-impl-sync.lock.yml) | Compiled agentic workflow that executes the reference implementation sync via `gh-aw` | `workflow_dispatch` | Tuesdays at 08:39 UTC (scattered) | | [Copilot Setup Steps](workflows/copilot-setup-steps.yml) | Configures the environment for the GitHub Copilot coding agent | `push` (on self-change), `workflow_dispatch` | — | --- @@ -21,9 +21,9 @@ Runs on every push to `main`, on pull requests, and in merge groups. Also runs w Steps: 1. Checks code formatting with Spotless -2. Compiles the SDK and clones the upstream test harness +2. Compiles the SDK and clones the reference implementation test harness 3. Verifies Javadoc generation -4. Installs the Copilot CLI from the cloned upstream SDK +4. Installs the Copilot CLI from the cloned reference implementation SDK 5. Runs the full test suite with `mvn verify` 6. Uploads test results (JaCoCo + Surefire) as artifacts for site generation @@ -53,7 +53,7 @@ Manual-only workflow that performs a full release: 1. Determines release and next development versions (auto-derived from `pom.xml` or manually specified) 2. Updates `CHANGELOG.md`, `README.md`, and `jbang-example.java` with the release version -3. Injects the upstream sync commit hash from `.lastmerge` into the changelog +3. Injects the reference implementation sync commit hash from `.lastmerge` into the changelog 4. Runs `mvn release:prepare` and `mvn release:perform` to deploy to Maven Central 5. Creates a GitHub Release with auto-generated notes 6. Moves the `latest` git tag forward @@ -62,26 +62,26 @@ Manual-only workflow that performs a full release: --- -## Weekly Upstream Sync +## Weekly Reference Implementation Sync -**File:** [`weekly-upstream-sync.yml`](workflows/weekly-upstream-sync.yml) +**File:** [`weekly-reference-impl-sync.yml`](workflows/weekly-reference-impl-sync.yml) Runs every Monday at 10:00 UTC. Clones the official `github/copilot-sdk` repository and compares `HEAD` against the commit hash stored in `.lastmerge`. If new commits are found: -1. Closes any previously open `upstream-sync` issues -2. Creates a new issue with a summary of upstream changes +1. Closes any previously open `reference-impl-sync` issues +2. Creates a new issue with a summary of reference implementation changes 3. Assigns the issue to `copilot-swe-agent` for automated porting -If no changes are found, any stale open `upstream-sync` issues are closed. +If no changes are found, any stale open `reference-impl-sync` issues are closed. --- -## Weekly Upstream Sync (Agentic Workflow: Experimental) +## Weekly Reference Implementation Sync (Agentic Workflow: Experimental) -**File:** [`weekly-upstream-sync.lock.yml`](workflows/weekly-upstream-sync.lock.yml) +**File:** [`weekly-reference-impl-sync.lock.yml`](workflows/weekly-reference-impl-sync.lock.yml) -Auto-generated compiled workflow produced by `gh aw compile` from the corresponding `.md` source. This is the agentic counterpart that actually executes the upstream merge using the `gh-aw` MCP server and Copilot coding agent. +Auto-generated compiled workflow produced by `gh aw compile` from the corresponding `.md` source. This is the agentic counterpart that actually executes the reference implementation merge using the `gh-aw` MCP server and Copilot coding agent. > **Do not edit this file directly.** Edit the `.md` source and run `gh aw compile`. @@ -98,3 +98,4 @@ Sets up: - JDK 17 (Temurin) - `gh-aw` CLI extension - Maven cache + diff --git a/docs/adr/adr-001-semver-pre-general-availability.md b/docs/adr/adr-001-semver-pre-general-availability.md index 44c9cf6db..33bdcc86c 100644 --- a/docs/adr/adr-001-semver-pre-general-availability.md +++ b/docs/adr/adr-001-semver-pre-general-availability.md @@ -20,8 +20,9 @@ We took an architectural decision to enable us to pursue investigating this poss Chosen option: "Track SemVer of reference implementation, with one exception.", because this enables us to pursue Virtual Threads without delaying the first public release of `copilot-sdk-java`. Also, we're supposed to be aggressively modernizing our customers. -To some extent, I would use qualifiers to mark a release as having some feature that is awaiting an upstream full release before it goes full ga, i.e you put out 0.1.46-virtualthreads.3 until upstream is ready to move to 0.2.0 then you release your virtual threads change and go 0.2.0. So I would make your agreement that your version numbers would match with the exception of qualifiers that you might add in exceptional circumstances. +To some extent, I would use qualifiers to mark a release as having some feature that is awaiting an reference implementation full release before it goes full ga, i.e you put out 0.1.46-virtualthreads.3 until reference implementation is ready to move to 0.2.0 then you release your virtual threads change and go 0.2.0. So I would make your agreement that your version numbers would match with the exception of qualifiers that you might add in exceptional circumstances. ## Related work items - https://devdiv.visualstudio.com/DevDiv/_workitems/edit/2745172 + diff --git a/docs/adr/adr-002-maven-version-and-reference-implementation-tracking.md b/docs/adr/adr-002-maven-version-and-reference-implementation-tracking.md index 7ef3d8ec8..6a0b54f22 100644 --- a/docs/adr/adr-002-maven-version-and-reference-implementation-tracking.md +++ b/docs/adr/adr-002-maven-version-and-reference-implementation-tracking.md @@ -6,7 +6,7 @@ Releases of this implementation track releases of the reference implementation. ## Considered Options -- Simple number qualifier (0.1.32-0, 0.1.32-1, ...) fails on a subtle but important point: 0.1.32-0 is treated identically to 0.1.32 by Maven (trailing zeros are normalized away), and bare numeric qualifiers are pre-release semantics. Your "first release" would sort before the upstream bare version. +- Simple number qualifier (0.1.32-0, 0.1.32-1, ...) fails on a subtle but important point: 0.1.32-0 is treated identically to 0.1.32 by Maven (trailing zeros are normalized away), and bare numeric qualifiers are pre-release semantics. Your "first release" would sort before the reference implementation bare version. - Java and number in the qualifier (0.1.32-java.N @@ -54,3 +54,4 @@ Everything looks healthy. Here's the status: ## Related work items - https://devdiv.visualstudio.com/DevDiv/_workitems/edit/2766089 + diff --git a/src/test/java/com/github/copilot/sdk/CommandsTest.java b/src/test/java/com/github/copilot/sdk/CommandsTest.java index baf26b39b..6bddbed28 100644 --- a/src/test/java/com/github/copilot/sdk/CommandsTest.java +++ b/src/test/java/com/github/copilot/sdk/CommandsTest.java @@ -25,7 +25,8 @@ * representation). * *

- * Ported from {@code CommandsTests.cs} in the upstream dotnet SDK. + * Ported from {@code CommandsTests.cs} in the reference implementation dotnet + * SDK. *

*/ class CommandsTest { diff --git a/src/test/java/com/github/copilot/sdk/ElicitationTest.java b/src/test/java/com/github/copilot/sdk/ElicitationTest.java index d6e2ac0b5..6b748b4cc 100644 --- a/src/test/java/com/github/copilot/sdk/ElicitationTest.java +++ b/src/test/java/com/github/copilot/sdk/ElicitationTest.java @@ -29,7 +29,8 @@ * Unit tests for the Elicitation feature and Session Capabilities. * *

- * Ported from {@code ElicitationTests.cs} in the upstream dotnet SDK. + * Ported from {@code ElicitationTests.cs} in the reference implementation + * dotnet SDK. *

*/ class ElicitationTest { diff --git a/src/test/java/com/github/copilot/sdk/HooksTest.java b/src/test/java/com/github/copilot/sdk/HooksTest.java index 05cd3292b..1278d082b 100644 --- a/src/test/java/com/github/copilot/sdk/HooksTest.java +++ b/src/test/java/com/github/copilot/sdk/HooksTest.java @@ -36,8 +36,8 @@ * *

* Note: Tests for userPromptSubmitted, sessionStart, and sessionEnd hooks are - * not included as they are not tested in the upstream .NET or Node.js SDKs and - * require test harness updates to properly invoke these hooks. + * not included as they are not tested in the reference implementation .NET or + * Node.js SDKs and require test harness updates to properly invoke these hooks. *

*/ public class HooksTest {