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<String, Object> — 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<String, McpServerConfig>. 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<String>) — preload named skill content into the agent's context
• ProviderConfig.setHeaders(Map<String, String>) — custom headers on outbound provider requests
• MessageOptions.setRequestHeaders(Map<String, String>) — per-turn headers on model requests
• CopilotSession.setModel(String, String, ModelCapabilitiesOverride) — new overload

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<String, Object> to Map<String, McpServerConfig>. 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.