Merge branch 'main' into morabbin/rust-session-memory-config

Author: Morabbin

.github/copilot-instructions.md

@@ -15,6 +15,7 @@
 - Test harness & E2E: `test/harness/*`, Python harness wrapper `python/e2e/testharness/proxy.py`
 - Schemas & type generation: `nodejs/scripts/generate-session-types.ts`
 - Session snapshots used by E2E: `test/snapshots/` (used by the replay proxy)
+- Docs style guide: `.github/instructions/docs-style.instructions.md` (used for `docs/**`)
 
 ## Developer workflows (commands you’ll use often) ▶️
 

.github/instructions/docs-style.instructions.md

@@ -0,0 +1,162 @@
+---
+applyTo: "docs/**"
+---
+
+# Copilot SDK docs style guide
+
+This style guide applies to all documentation in the `docs/` directory. These docs are synced to `github/docs-internal` via a normalization pipeline, so they must follow the conventions below to be compatible with docs.github.com.
+
+## Headings
+
+Use **sentence case** for all headings. Capitalize only the first word and proper nouns.
+
+* `## Quick start: Azure AI Foundry` — not `## Quick Start: Azure AI Foundry`
+* `# Custom agents and sub-agent orchestration` — not `# Custom Agents & Sub-Agent Orchestration`
+
+Use `and` instead of `&` in headings.
+
+Do not use `**bold**` or `*italic*` markers inside headings. The heading level provides emphasis.
+
+### Proper nouns to always capitalize
+
+* Products/companies: GitHub, Copilot, Azure, OpenAI, Anthropic, Microsoft, Ollama, Slack, Foundry, Kubernetes, Docker
+* Languages/frameworks: TypeScript, JavaScript, Python, Java, Node.js, OpenTelemetry, Express
+* Platforms: macOS, Linux, Windows
+* Protocols/formats: OAuth, JSON-RPC, JSON, YAML, HTTP, TCP, SSE, REST
+* Acronyms: MCP, BYOK, MAF, SDK, CLI, API, HMAC, CI/CD, SaaS, ISV, FAQ, LLM, AI, EMU, ID, UI, PNG
+* Tools (keep canonical casing): npm, npx, stdio
+* Code identifiers in headings: SessionConfig, MessageOptions, TelemetryConfig, ProviderConfig, CopilotClient
+* Multi-word proper names: GitHub App, GitHub Actions, GitHub OAuth, Foundry Local, Azure AD, Container Instances
+
+## Callouts
+
+Use GitHub-flavored alert syntax:
+
+```markdown
+> [!NOTE]
+> This is a note.
+
+> [!TIP]
+> This is a tip.
+
+> [!WARNING]
+> This is a warning.
+```
+
+Never use `> **Note:**` or `> **Tip:**` style callouts.
+
+When a callout applies to a specific language, put the qualifier as bold text in the body:
+
+```markdown
+> [!TIP]
+> **(Python / Go)** These SDKs use a single `Data` class/struct with all fields optional.
+```
+
+## Lists
+
+### Unordered lists
+
+Use `*` (asterisks) for unordered list markers, not `-` (hyphens).
+
+### Ordered lists
+
+Use `1.` for every item in ordered lists, not sequential numbering. This makes reordering easier.
+
+```markdown
+1. First step
+1. Second step
+1. Third step
+```
+
+### List item formatting
+
+* Capitalize the first letter of each list item.
+* Use periods only if the item is a complete sentence.
+* Introduce lists with a descriptive sentence, not vague phrases like "the following" in isolation.
+
+## Em dashes
+
+For list items with a **label and description**, use a colon:
+
+```markdown
+* **Ephemeral**: not persisted to disk, not replayed on session resume
+```
+
+For em dashes used mid-sentence, use no spaces:
+
+```markdown
+The SDK is a transport layer—it sends your prompt to the CLI over JSON-RPC.
+```
+
+## Horizontal rules
+
+Do not use `---` as a horizontal rule to visually separate sections in the body of an article. Use headings to separate sections instead. This does not apply to YAML frontmatter delimiters.
+
+## Index.md files
+
+In the docs pipeline, `index.md` files become YAML-only category pages. Rich content (prose, code samples, diagrams) must live in standalone files.
+
+If you are writing a new section with substantive content, create a named file (for example, `choosing-a-setup-path.md`) rather than putting the content in `index.md`.
+
+## Code snippets
+
+* Only modify code block contents when necessary. Keep all examples passing the SDK team's `docs-validate` workflow, rerun validation after changes, and use `docs-validate: skip` or `docs-validate: hidden` markers when appropriate.
+
+## Voice and tone
+
+* Use clear, simple language approachable for a wide range of readers.
+* Use active voice whenever possible.
+* Avoid idioms, slang, and region-specific phrases.
+* Avoid ambiguous modal verbs ("may", "might", "should", "could") when an action is required. Use definitive verbs instead.
+* Refer to people as "people" or "users", not "customers."
+
+## Emphasis
+
+* Use **bold** for UI elements and for emphasis, sparingly (no more than five contiguous words).
+* Do not bold text that already has other formatting (for example, all-caps placeholders).
+
+## Word choice
+
+| Use | Avoid |
+|---|---|
+| terminal | shell |
+| sign in | log in, login |
+| sign up | signup |
+| email | e-mail |
+| press (a key) | hit, tap |
+| repository | repo |
+| administrator | admin |
+| for example | e.g. |
+| and similar | etc. |
+
+## What the pipeline handles
+
+Authors do not need to worry about these — the normalization pipeline handles them automatically:
+
+* YAML frontmatter (added to files for docs.github.com)
+* Mermaid diagram → PNG conversion
+* Link rewriting for docs.github.com cross-references
+* Liquid variable substitution (product names)
+* `[AUTOTITLE]` link conversion
+
+## New article template
+
+When creating a new docs article, use this structure:
+
+```markdown
+# Article title in sentence case
+
+A one- or two-sentence intro explaining what the reader will learn or accomplish.
+
+## First section
+
+Body text here.
+
+## Second section
+
+Body text here.
+
+## Further reading
+
+* [Link text](./relative-path.md): short description
+```

java/README.md

@@ -30,14 +30,14 @@ Replace `${copilot.sdk.version}` with the latest release from Maven Central.
 <dependency>
     <groupId>com.github</groupId>
     <artifactId>copilot-sdk-java</artifactId>
-    <version>1.0.0</version>
+    <version>1.0.1</version>
 </dependency>
 ```
 
 ### Gradle
 
 ```groovy
-implementation 'com.github:copilot-sdk-java:1.0.0'
+implementation 'com.github:copilot-sdk-java:1.0.1'
 ```
 
 #### Snapshot Builds
@@ -56,7 +56,7 @@ Snapshot builds of the next development version are published to Maven Central S
 <dependency>
     <groupId>com.github</groupId>
     <artifactId>copilot-sdk-java</artifactId>
-    <version>1.0.1-SNAPSHOT</version>
+    <version>1.0.2-SNAPSHOT</version>
 </dependency>
 ```
 
@@ -65,7 +65,7 @@ Snapshot builds of the next development version are published to Maven Central S
 Replace `${copilot.sdk.version}` with the latest release from Maven Central.
 
 ```groovy
-implementation 'com.github:copilot-sdk-java:1.0.0-SNAPSHOT'
+implementation 'com.github:copilot-sdk-java:1.0.2-SNAPSHOT'
 ```
 
 ## Quick Start

java/jbang-example.java

@@ -1,5 +1,5 @@
 ///usr/bin/env jbang "$0" "$@" ; exit $?
-//DEPS com.github:copilot-sdk-java:1.0.0
+//DEPS com.github:copilot-sdk-java:1.0.1
 import com.github.copilot.CopilotClient;
 import com.github.copilot.generated.AssistantMessageEvent;
 import com.github.copilot.generated.SessionUsageInfoEvent;

java/pom.xml

@@ -7,7 +7,7 @@
 
     <groupId>com.github</groupId>
     <artifactId>copilot-sdk-java</artifactId>
-    <version>1.0.1-SNAPSHOT</version>
+    <version>1.0.2-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <name>GitHub Copilot SDK :: Java</name>
@@ -112,7 +112,7 @@
         <dependency>
             <groupId>com.github.spotbugs</groupId>
             <artifactId>spotbugs-annotations</artifactId>
-            <version>4.9.8</version>
+            <version>4.10.2</version>
             <scope>provided</scope>
         </dependency>
 
@@ -147,7 +147,7 @@
                 <plugin>
                     <groupId>com.github.spotbugs</groupId>
                     <artifactId>spotbugs-maven-plugin</artifactId>
-                    <version>4.9.8.3</version>
+                    <version>4.10.2.0</version>
                     <configuration>
                         <excludeFilterFile>config/spotbugs/spotbugs-exclude.xml</excludeFilterFile>
                     </configuration>
@@ -384,7 +384,7 @@
             <plugin>
                 <groupId>org.jacoco</groupId>
                 <artifactId>jacoco-maven-plugin</artifactId>
-                <version>0.8.14</version>
+                <version>0.8.15</version>
                 <executions>
                     <!-- Instrument bytecode before E2ETestContext runs tests with CapiProxy -->
                     <execution>

java/scripts/codegen/java.ts

@@ -2059,6 +2059,12 @@ async function main(): Promise<void> {
     console.log("🚀 Java SDK code generator");
     console.log("============================");
 
+    // Clean the generated output directory to remove orphaned files from previous runs
+    const generatedOutputDir = path.join(REPO_ROOT, "src/generated/java/com/github/copilot/generated");
+    console.log(`🧹 Cleaning output directory: ${generatedOutputDir}`);
+    await fs.rm(generatedOutputDir, { recursive: true, force: true });
+    await fs.mkdir(generatedOutputDir, { recursive: true });
+
     const sessionEventsSchemaPath = await getSessionEventsSchemaPath();
     console.log(`📄 Session events schema: ${sessionEventsSchemaPath}`);
     const apiSchemaPath = await getApiSchemaPath();