Reference implementation sync: 41 new commits (2026-04-20)

[Copilot]

Ports 41 new commits from the official github/copilot-sdk reference implementation into the Java SDK, updating the API to match the latest feature set.

---

Before the change?

• SessionConfig/ResumeSessionConfig had no way to override model capabilities, control sub-agent streaming events, or enable config discovery
• McpServers typed as Map — no type safety
• CustomAgentConfig had no skills field for per-agent skill preloading
• ProviderConfig had no headers field; MessageOptions had no requestHeaders for per-turn headers
• CopilotSession.setModel() had no overload accepting capability overrides
• .lastmerge pointed to c3fa6cbfb83d4a20b7912b1a17013d48f5a277a1

After the change?

New types (hand-authored in json package — not candidates for java.ts codegen):

• McpServerConfig — abstract base with typed subclasses McpStdioServerConfig (local/stdio) and McpHttpServerConfig (remote HTTP/SSE); McpServers is now Map. The mcpServers field is absent from api.schema.json, so these cannot be generated.
• ModelCapabilitiesOverride — per-property overrides for model capabilities (vision, reasoning effort, token limits). While modelCapabilities appears in api.schema.json under session.model.switchTo.params, the codegen already generates it as the verbose inner record SessionModelSwitchToParamsModelCapabilities. A hand-authored class is required because session.create and session.resume are not in the schema, and the codegen has no mechanism to emit standalone named types shared across hand-authored request classes.

API additions on SessionConfig / ResumeSessionConfig:

• setModelCapabilities(ModelCapabilitiesOverride) — deep-merged over runtime defaults
• setIncludeSubAgentStreamingEvents(Boolean) — suppress/expose streaming deltas from sub-agents
• setEnableConfigDiscovery(Boolean) — auto-discover MCP configs and skill dirs from working dir

Other additions:

• CustomAgentConfig.setSkills(List) — preload named skill content into the agent's context
• ProviderConfig.setHeaders(Map) — custom headers on outbound provider requests; imports reordered to place java.* before com.* per codebase convention
• MessageOptions.setRequestHeaders(Map) — per-turn headers on model requests
• CopilotSession.setModel(String, String, ModelCapabilitiesOverride) — new overload; now correctly maps both supports and limits from ModelCapabilitiesOverride into the generated params (including Integer→Double conversion for limit fields), so token limit overrides are properly honored when switching models

Example — disable vision for a session then re-enable on model switch:

var session = client.createSession(new SessionConfig()
    .setModel("claude-sonnet-4.5")
    .setModelCapabilities(new ModelCapabilitiesOverride()
        .setSupports(new ModelCapabilitiesOverride.Supports().setVision(false)))).get();

// Later, re-enable vision
session.setModel("claude-sonnet-4.5", null,
    new ModelCapabilitiesOverride().setSupports(new ModelCapabilitiesOverride.Supports().setVision(true))).get();

Example — per-agent skills with typed MCP server:

var agent = new CustomAgentConfig()
    .setName("my-agent")
    .setSkills(List.of("my-skill"));

var server = new McpStdioServerConfig()
    .setCommand("npx").setArgs(List.of("-y", "@mcp/server")).setTools(List.of("*"));

var config = new SessionConfig()
    .setSkillDirectories(List.of("/path/to/skills"))
    .setCustomAgents(List.of(agent))
    .setMcpServers(Map.of("my-server", server));

Test updates:

• McpAndAgentsTest migrated to typed McpStdioServerConfig API
• SkillsTest — added tests for per-agent skill injection (skills field)
• Removed setModel("fake-test-model") from CopilotSessionTest / ClosedSessionGuardTest — the new CLI validates model availability against the /models list
• .lastmerge updated to 922959f4a7b83509c3620d4881733c6c5677f00c

Pull request checklist

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
• mvn spotless:apply has been run to format the code
• mvn clean verify passes locally

Does this introduce a breaking change?

• Yes
• No

SessionConfig.getMcpServers() / setMcpServers() return type changed from Map to Map. Similarly for ResumeSessionConfig and CustomAgentConfig. Callers using raw maps must migrate to McpStdioServerConfig or McpHttpServerConfig.

---

[edburns]

@copilot

I am concerned that some of the new classes might better be made to come from the java.ts code generator.

Please know that all classes that can be generated from the Zod schemas, as shown in the update-copilot-dependency workflow, should be generated there, rather than hand authored.

Please double check that none of these classes in the json package are better suited for java.ts code gen.

[Copilot]

@copilot

I am concerned that some of the new classes might better be made to come from the java.ts code generator....

Good question — I investigated thoroughly. None of the four new classes are candidates for the codegen:

McpServerConfig, McpStdioServerConfig, McpHttpServerConfig
The mcpServers field is completely absent from api.schema.json. The schema has no knowledge of these types. They cannot be generated.

ModelCapabilitiesOverride
The modelCapabilities property does appear in the schema — but only inside the session.model.switchTo params. The codegen already generates it as the inner record SessionModelSwitchToParamsModelCapabilities (inside SessionModelSwitchToParams.java). However, it cannot be code-generated as a standalone class for two reasons:

1. session.create and session.resume are not in api.schema.json (the schema has no session.create, session.resume, or session.send methods — only things like session.model.switchTo, session.mcp.list, etc.). All the types that feed into CreateSessionRequest and ResumeSessionRequest are hand-authored because those RPC methods are outside the schema's scope.

2. The current java.ts codegen generates nested anonymous records inside a single class — it has no mechanism to emit a standalone named type that can be shared across multiple hand-authored classes. To use the generated SessionModelSwitchToParamsModelCapabilities directly in SessionConfig.setModelCapabilities() would force users to spell out a very verbose generated name.

The hand-authored ModelCapabilitiesOverride acts as the clean public API type for SessionConfig and CopilotSession.setModel(), and the converter in setModel(String, String, ModelCapabilitiesOverride) bridges it to the generated wire type.

[edburns]

@brunoborges do you want to review the first Agentic Sync since the code gen is introduced?

[Copilot]

Pull request overview

Ports upstream github/copilot-sdk changes into the Java SDK, expanding session configuration and request capabilities (typed MCP servers, model capability overrides, per-turn/provider headers, and agent skill preloading) to stay API-parity with the reference implementation.

Changes:

• Add typed MCP server configuration (McpServerConfig + stdio/http subclasses) and update *Config/request DTOs to use Map<String, McpServerConfig>.
• Add session/resume options for config discovery + sub-agent streaming event inclusion + model capability overrides, and wire them into request building.
• Add agent skills preloading and per-turn/provider request headers support; update/extend tests accordingly.

Show a summary per file

File	Description
src/test/java/com/github/copilot/sdk/SkillsTest.java	Adds coverage for per-agent skills injection behavior via snapshots.
src/test/java/com/github/copilot/sdk/McpAndAgentsTest.java	Migrates MCP tests to typed McpServerConfig APIs.
src/test/java/com/github/copilot/sdk/CopilotSessionTest.java	Removes hardcoded fake model to align with stricter CLI model validation.
src/test/java/com/github/copilot/sdk/ClosedSessionGuardTest.java	Removes hardcoded fake model to align with stricter CLI model validation.
src/main/java/com/github/copilot/sdk/json/SessionConfig.java	Adds new session options and types MCP servers as Map<String, McpServerConfig>.
src/main/java/com/github/copilot/sdk/json/SendMessageRequest.java	Adds requestHeaders field for per-turn headers on session.send.
src/main/java/com/github/copilot/sdk/json/ResumeSessionRequest.java	Adds config discovery/sub-agent streaming/model capability overrides + typed MCP servers.
src/main/java/com/github/copilot/sdk/json/ResumeSessionConfig.java	Adds config discovery/sub-agent streaming/model capability overrides + typed MCP servers.
src/main/java/com/github/copilot/sdk/json/ProviderConfig.java	Adds outbound provider headers map.
src/main/java/com/github/copilot/sdk/json/ModelCapabilitiesOverride.java	Introduces a named override type for model supports/limits (hand-authored).
src/main/java/com/github/copilot/sdk/json/MessageOptions.java	Adds per-turn requestHeaders and clones them safely.
src/main/java/com/github/copilot/sdk/json/McpStdioServerConfig.java	Adds concrete stdio/local MCP server config DTO.
src/main/java/com/github/copilot/sdk/json/McpServerConfig.java	Adds polymorphic MCP server base type with type discriminator.
src/main/java/com/github/copilot/sdk/json/McpHttpServerConfig.java	Adds concrete HTTP/SSE MCP server config DTO.
src/main/java/com/github/copilot/sdk/json/CustomAgentConfig.java	Adds typed MCP servers and skills preload list for agents.
src/main/java/com/github/copilot/sdk/json/CreateSessionRequest.java	Wires new create-session request fields (capabilities, discovery, sub-agent streaming, typed MCP).
src/main/java/com/github/copilot/sdk/SessionRequestBuilder.java	Propagates new config fields into create/resume request payloads.
src/main/java/com/github/copilot/sdk/CopilotSession.java	Adds setModel overload that accepts model capability overrides; wires per-turn headers into send request.
.lastmerge	Advances recorded upstream sync commit.

Copilot's findings

• Files reviewed: 19/19 changed files
• Comments generated: 2

[Copilot]

CopilotSession#setModel(String, String, ModelCapabilitiesOverride) only maps modelCapabilities.supports into the generated SessionModelSwitchToParamsModelCapabilities and always passes limits as null. This means token limit overrides (and any future limits fields) provided by callers are silently ignored when switching models, despite ModelCapabilitiesOverride supporting them and the Javadoc implying they apply. Map ModelCapabilitiesOverride.getLimits() into SessionModelSwitchToParamsModelCapabilitiesLimits (converting Integer to Double as needed) and pass it into the generated capabilities record so model switches honor limit overrides too.

Suggested change

	generatedCapabilities = new SessionModelSwitchToParams.SessionModelSwitchToParamsModelCapabilities(supports,
	null);
	SessionModelSwitchToParams.SessionModelSwitchToParamsModelCapabilities.SessionModelSwitchToParamsModelCapabilitiesLimits limits = null;
	if (modelCapabilities.getLimits() != null) {
	limits = new ObjectMapper().convertValue(modelCapabilities.getLimits(),
	SessionModelSwitchToParams.SessionModelSwitchToParamsModelCapabilities.SessionModelSwitchToParamsModelCapabilitiesLimits.class);
	}
	generatedCapabilities = new SessionModelSwitchToParams.SessionModelSwitchToParamsModelCapabilities(supports,
	limits);

[Copilot]

Fixed in def5449. Now maps modelCapabilities.getLimits() into SessionModelSwitchToParamsModelCapabilitiesLimits via ObjectMapper.convertValue() (handling the Integer→Double conversion) and passes it to the capabilities record instead of null.

[Copilot]

Import grouping in this file is inconsistent with the surrounding codebase (most files place java.* imports before third-party com.* imports). Consider moving the java.util.* imports above the Jackson imports to match the prevailing convention and avoid churn if an import organizer is applied later.

Suggested change

	import com.fasterxml.jackson.annotation.JsonInclude;
	import com.fasterxml.jackson.annotation.JsonProperty;
	import java.util.Collections;
	import java.util.Map;
	import java.util.Collections;
	import java.util.Map;
	import com.fasterxml.jackson.annotation.JsonInclude;
	import com.fasterxml.jackson.annotation.JsonProperty;

[Copilot]

Fixed in def5449. Moved java.* imports above the Jackson com.* imports in ProviderConfig.java.