SessionConfig.java
/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
*--------------------------------------------------------------------------------------------*/
package com.github.copilot.sdk.json;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;
import java.util.function.Consumer;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.github.copilot.sdk.generated.SessionEvent;
/**
* Configuration for creating a new Copilot session.
* <p>
* This class provides options for customizing session behavior, including model
* selection, tool registration, system message customization, and more. All
* setter methods return {@code this} for method chaining.
*
* <h2>Example Usage</h2>
*
* <pre>{@code
* var config = new SessionConfig().setModel("gpt-5").setStreaming(true).setSystemMessage(
* new SystemMessageConfig().setMode(SystemMessageMode.APPEND).setContent("Be concise in your responses."));
*
* var session = client.createSession(config).get();
* }</pre>
*
* @see com.github.copilot.sdk.CopilotClient#createSession(SessionConfig)
* @since 1.0.0
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public class SessionConfig {
private String sessionId;
private String clientName;
private String model;
private String reasoningEffort;
private List<ToolDefinition> tools;
private SystemMessageConfig systemMessage;
private List<String> availableTools;
private List<String> excludedTools;
private ProviderConfig provider;
private PermissionHandler onPermissionRequest;
private UserInputHandler onUserInputRequest;
private SessionHooks hooks;
private String workingDirectory;
private boolean streaming;
private Boolean includeSubAgentStreamingEvents;
private Map<String, McpServerConfig> mcpServers;
private List<CustomAgentConfig> customAgents;
private DefaultAgentConfig defaultAgent;
private String agent;
private InfiniteSessionConfig infiniteSessions;
private List<String> skillDirectories;
private List<String> disabledSkills;
private String configDir;
private Boolean enableConfigDiscovery;
private ModelCapabilitiesOverride modelCapabilities;
private Consumer<SessionEvent> onEvent;
private List<CommandDefinition> commands;
private ElicitationHandler onElicitationRequest;
private String gitHubToken;
/**
* Gets the custom session ID.
*
* @return the session ID, or {@code null} to generate automatically
*/
public String getSessionId() {
return sessionId;
}
/**
* Sets a custom session ID.
* <p>
* If not provided, a unique session ID will be generated automatically.
*
* @param sessionId
* the custom session ID
* @return this config instance for method chaining
*/
public SessionConfig setSessionId(String sessionId) {
this.sessionId = sessionId;
return this;
}
/**
* Gets the client name used to identify the application using the SDK.
*
* @return the client name, or {@code null} if not set
*/
public String getClientName() {
return clientName;
}
/**
* Sets the client name to identify the application using the SDK.
* <p>
* This value is included in the User-Agent header for API requests.
*
* @param clientName
* the client name
* @return this config instance for method chaining
*/
public SessionConfig setClientName(String clientName) {
this.clientName = clientName;
return this;
}
/**
* Gets the AI model to use.
*
* @return the model name
*/
public String getModel() {
return model;
}
/**
* Sets the AI model to use for this session.
* <p>
* Examples: "gpt-5", "claude-sonnet-4.5", "o3-mini".
*
* @param model
* the model name
* @return this config instance for method chaining
*/
public SessionConfig setModel(String model) {
this.model = model;
return this;
}
/**
* Gets the reasoning effort level.
*
* @return the reasoning effort level ("low", "medium", "high", or "xhigh")
*/
public String getReasoningEffort() {
return reasoningEffort;
}
/**
* Sets the reasoning effort level for models that support it.
* <p>
* Valid values: "low", "medium", "high", "xhigh". Only applies to models where
* {@code capabilities.supports.reasoningEffort} is true.
*
* @param reasoningEffort
* the reasoning effort level
* @return this config instance for method chaining
*/
public SessionConfig setReasoningEffort(String reasoningEffort) {
this.reasoningEffort = reasoningEffort;
return this;
}
/**
* Gets the custom tools for this session.
*
* @return the list of tool definitions
*/
public List<ToolDefinition> getTools() {
return tools == null ? null : Collections.unmodifiableList(tools);
}
/**
* Sets custom tools that the assistant can invoke during the session.
* <p>
* Tools allow the assistant to call back into your application to perform
* actions or retrieve information.
*
* @param tools
* the list of tool definitions
* @return this config instance for method chaining
* @see ToolDefinition
*/
public SessionConfig setTools(List<ToolDefinition> tools) {
this.tools = tools;
return this;
}
/**
* Gets the system message configuration.
*
* @return the system message config
*/
public SystemMessageConfig getSystemMessage() {
return systemMessage;
}
/**
* Sets the system message configuration.
* <p>
* The system message controls the behavior and personality of the assistant.
* Use {@link com.github.copilot.sdk.SystemMessageMode#APPEND} to add
* instructions while preserving default behavior, or
* {@link com.github.copilot.sdk.SystemMessageMode#REPLACE} to fully customize.
*
* @param systemMessage
* the system message configuration
* @return this config instance for method chaining
* @see SystemMessageConfig
*/
public SessionConfig setSystemMessage(SystemMessageConfig systemMessage) {
this.systemMessage = systemMessage;
return this;
}
/**
* Gets the list of allowed tool names.
*
* @return the list of available tool names
*/
public List<String> getAvailableTools() {
return availableTools == null ? null : Collections.unmodifiableList(availableTools);
}
/**
* Sets the list of tool names that are allowed in this session.
* <p>
* When specified, only tools in this list will be available to the assistant.
*
* @param availableTools
* the list of allowed tool names
* @return this config instance for method chaining
*/
public SessionConfig setAvailableTools(List<String> availableTools) {
this.availableTools = availableTools;
return this;
}
/**
* Gets the list of excluded tool names.
*
* @return the list of excluded tool names
*/
public List<String> getExcludedTools() {
return excludedTools == null ? null : Collections.unmodifiableList(excludedTools);
}
/**
* Sets the list of tool names to exclude from this session.
* <p>
* Tools in this list will not be available to the assistant.
*
* @param excludedTools
* the list of tool names to exclude
* @return this config instance for method chaining
*/
public SessionConfig setExcludedTools(List<String> excludedTools) {
this.excludedTools = excludedTools;
return this;
}
/**
* Gets the custom API provider configuration.
*
* @return the provider configuration
*/
public ProviderConfig getProvider() {
return provider;
}
/**
* Sets a custom API provider for BYOK (Bring Your Own Key) scenarios.
* <p>
* This allows using your own OpenAI, Azure OpenAI, or other compatible API
* endpoints instead of the default Copilot backend.
*
* @param provider
* the provider configuration
* @return this config instance for method chaining
* @see ProviderConfig
*/
public SessionConfig setProvider(ProviderConfig provider) {
this.provider = provider;
return this;
}
/**
* Gets the permission request handler.
*
* @return the permission handler
*/
public PermissionHandler getOnPermissionRequest() {
return onPermissionRequest;
}
/**
* Sets a handler for permission requests from the assistant.
* <p>
* When the assistant needs permission to perform certain actions, this handler
* will be invoked to approve or deny the request.
*
* @param onPermissionRequest
* the permission handler
* @return this config instance for method chaining
* @see PermissionHandler
*/
public SessionConfig setOnPermissionRequest(PermissionHandler onPermissionRequest) {
this.onPermissionRequest = onPermissionRequest;
return this;
}
/**
* Gets the user input request handler.
*
* @return the user input handler
*/
public UserInputHandler getOnUserInputRequest() {
return onUserInputRequest;
}
/**
* Sets a handler for user input requests from the agent.
* <p>
* When provided, enables the ask_user tool for the agent to request user input.
*
* @param onUserInputRequest
* the user input handler
* @return this config instance for method chaining
* @see UserInputHandler
*/
public SessionConfig setOnUserInputRequest(UserInputHandler onUserInputRequest) {
this.onUserInputRequest = onUserInputRequest;
return this;
}
/**
* Gets the hook handlers configuration.
*
* @return the session hooks
*/
public SessionHooks getHooks() {
return hooks;
}
/**
* Sets hook handlers for session lifecycle events.
* <p>
* Hooks allow you to intercept and modify tool execution behavior.
*
* @param hooks
* the hooks configuration
* @return this config instance for method chaining
* @see SessionHooks
*/
public SessionConfig setHooks(SessionHooks hooks) {
this.hooks = hooks;
return this;
}
/**
* Gets the working directory for the session.
*
* @return the working directory path
*/
public String getWorkingDirectory() {
return workingDirectory;
}
/**
* Sets the working directory for the session.
*
* @param workingDirectory
* the working directory path
* @return this config instance for method chaining
*/
public SessionConfig setWorkingDirectory(String workingDirectory) {
this.workingDirectory = workingDirectory;
return this;
}
/**
* Returns whether streaming is enabled.
*
* @return {@code true} if streaming is enabled
*/
public boolean isStreaming() {
return streaming;
}
/**
* Sets whether to enable streaming of response chunks.
* <p>
* When enabled, the session will emit {@code AssistantMessageDeltaEvent} events
* as the response is generated, allowing for real-time display of partial
* responses.
*
* @param streaming
* {@code true} to enable streaming
* @return this config instance for method chaining
*/
public SessionConfig setStreaming(boolean streaming) {
this.streaming = streaming;
return this;
}
/**
* Gets the MCP server configurations.
*
* @return the MCP servers map
*/
public Map<String, McpServerConfig> getMcpServers() {
return mcpServers == null ? null : Collections.unmodifiableMap(mcpServers);
}
/**
* Sets MCP (Model Context Protocol) server configurations.
* <p>
* MCP servers extend the assistant's capabilities by providing additional
* context sources and tools.
*
* @param mcpServers
* the MCP servers configuration map
* @return this config instance for method chaining
*/
public SessionConfig setMcpServers(Map<String, McpServerConfig> mcpServers) {
this.mcpServers = mcpServers;
return this;
}
/**
* Gets the custom agent configurations.
*
* @return the list of custom agent configurations
*/
public List<CustomAgentConfig> getCustomAgents() {
return customAgents == null ? null : Collections.unmodifiableList(customAgents);
}
/**
* Sets custom agent configurations.
* <p>
* Custom agents allow extending the assistant with specialized behaviors and
* capabilities.
*
* @param customAgents
* the list of custom agent configurations
* @return this config instance for method chaining
* @see CustomAgentConfig
*/
public SessionConfig setCustomAgents(List<CustomAgentConfig> customAgents) {
this.customAgents = customAgents;
return this;
}
/**
* Gets the default agent configuration.
*
* @return the default agent configuration, or {@code null} if not set
*/
public DefaultAgentConfig getDefaultAgent() {
return defaultAgent;
}
/**
* Sets the default agent configuration.
* <p>
* Use {@link DefaultAgentConfig#setExcludedTools(List)} to hide specific tools
* from the default agent while keeping them available to custom sub-agents.
*
* @param defaultAgent
* the default agent configuration
* @return this config instance for method chaining
* @see DefaultAgentConfig
*/
public SessionConfig setDefaultAgent(DefaultAgentConfig defaultAgent) {
this.defaultAgent = defaultAgent;
return this;
}
/**
* Gets the name of the custom agent to activate at session start.
*
* @return the agent name, or {@code null} if not set
*/
public String getAgent() {
return agent;
}
/**
* Sets the name of the custom agent to activate when the session starts.
* <p>
* Must match the name of one of the agents in {@link #setCustomAgents(List)}.
*
* @param agent
* the agent name to pre-select
* @return this config instance for method chaining
*/
public SessionConfig setAgent(String agent) {
this.agent = agent;
return this;
}
/**
* Gets the infinite sessions configuration.
*
* @return the infinite sessions config
*/
public InfiniteSessionConfig getInfiniteSessions() {
return infiniteSessions;
}
/**
* Sets the infinite session configuration for persistent workspaces and
* automatic compaction.
* <p>
* When enabled (default), sessions automatically manage context limits and
* persist state to a workspace directory. The workspace contains checkpoints/,
* plan.md, and files/ subdirectories.
*
* @param infiniteSessions
* the infinite sessions configuration
* @return this config instance for method chaining
* @see InfiniteSessionConfig
*/
public SessionConfig setInfiniteSessions(InfiniteSessionConfig infiniteSessions) {
this.infiniteSessions = infiniteSessions;
return this;
}
/**
* Gets the skill directories.
*
* @return the list of skill directory paths
*/
public List<String> getSkillDirectories() {
return skillDirectories == null ? null : Collections.unmodifiableList(skillDirectories);
}
/**
* Sets the skill directories for loading custom skills.
* <p>
* Skills are loaded from SKILL.md files in subdirectories of the specified
* directories. Each skill subdirectory should contain a SKILL.md file with YAML
* frontmatter defining the skill metadata.
*
* @param skillDirectories
* the list of skill directory paths
* @return this config instance for method chaining
*/
public SessionConfig setSkillDirectories(List<String> skillDirectories) {
this.skillDirectories = skillDirectories;
return this;
}
/**
* Gets the disabled skill names.
*
* @return the list of disabled skill names
*/
public List<String> getDisabledSkills() {
return disabledSkills == null ? null : Collections.unmodifiableList(disabledSkills);
}
/**
* Sets the list of skill names to disable.
* <p>
* Skills in this list will not be applied to the session, even if they are
* found in the skill directories.
*
* @param disabledSkills
* the list of skill names to disable
* @return this config instance for method chaining
*/
public SessionConfig setDisabledSkills(List<String> disabledSkills) {
this.disabledSkills = disabledSkills;
return this;
}
/**
* Gets the custom configuration directory.
*
* @return the config directory path
*/
public String getConfigDir() {
return configDir;
}
/**
* Sets a custom configuration directory for the session.
* <p>
* This allows using a specific directory for session configuration instead of
* the default location.
*
* @param configDir
* the configuration directory path
* @return this config instance for method chaining
*/
public SessionConfig setConfigDir(String configDir) {
this.configDir = configDir;
return this;
}
/**
* Gets whether automatic configuration discovery is enabled.
*
* @return {@code true} to enable discovery, {@code false} to disable, or
* {@code null} to use the runtime default
*/
public Boolean getEnableConfigDiscovery() {
return enableConfigDiscovery;
}
/**
* Sets whether to automatically discover MCP server configurations and skill
* directories from the working directory.
* <p>
* When {@code true}, the CLI scans the working directory for {@code .mcp.json},
* {@code .vscode/mcp.json} and skill directories, and merges them with
* explicitly provided {@link #setMcpServers(Map)} and
* {@link #setSkillDirectories(List)}, with explicit values taking precedence on
* name collision.
*
* @param enableConfigDiscovery
* {@code true} to enable discovery, {@code false} to disable, or
* {@code null} to use the runtime default
* @return this config instance for method chaining
*/
public SessionConfig setEnableConfigDiscovery(Boolean enableConfigDiscovery) {
this.enableConfigDiscovery = enableConfigDiscovery;
return this;
}
/**
* Gets whether sub-agent streaming events are included.
*
* @return {@code true} to include sub-agent streaming events, {@code false} to
* suppress them, or {@code null} to use the runtime default
*/
public Boolean getIncludeSubAgentStreamingEvents() {
return includeSubAgentStreamingEvents;
}
/**
* Sets whether to include sub-agent streaming events in the event stream.
* <p>
* When {@code true}, streaming delta events from sub-agents (e.g.,
* {@code assistant.message_delta} with {@code agentId} set) are forwarded to
* this connection. When {@code false}, only non-streaming sub-agent events and
* {@code subagent.*} lifecycle events are forwarded; streaming deltas from
* sub-agents are suppressed. Default: {@code true}.
*
* @param includeSubAgentStreamingEvents
* {@code true} to include streaming events, {@code false} to
* suppress
* @return this config instance for method chaining
*/
public SessionConfig setIncludeSubAgentStreamingEvents(Boolean includeSubAgentStreamingEvents) {
this.includeSubAgentStreamingEvents = includeSubAgentStreamingEvents;
return this;
}
/**
* Gets the model capabilities override.
*
* @return the model capabilities override, or {@code null} if not set
*/
public ModelCapabilitiesOverride getModelCapabilities() {
return modelCapabilities;
}
/**
* Sets per-property overrides for model capabilities, deep-merged over runtime
* defaults.
* <p>
* Use this to override specific model capabilities (such as vision support) for
* this session. Only non-null fields in the override are applied; unset fields
* retain their runtime defaults.
*
* @param modelCapabilities
* the model capabilities override
* @return this config instance for method chaining
* @see ModelCapabilitiesOverride
*/
public SessionConfig setModelCapabilities(ModelCapabilitiesOverride modelCapabilities) {
this.modelCapabilities = modelCapabilities;
return this;
}
/**
* Gets the event handler registered before the session.create RPC is issued.
*
* @return the event handler, or {@code null} if not set
*/
public Consumer<SessionEvent> getOnEvent() {
return onEvent;
}
/**
* Sets an event handler that is registered on the session before the
* {@code session.create} RPC is issued.
* <p>
* Equivalent to calling
* {@link com.github.copilot.sdk.CopilotSession#on(Consumer)} immediately after
* creation, but executes earlier in the lifecycle so no events are missed.
* Using this property rather than {@code CopilotSession.on()} guarantees that
* early events emitted by the CLI during session creation (e.g.
* {@code session.start}) are delivered to the handler.
*
* @param onEvent
* the event handler to register before session creation
* @return this config instance for method chaining
*/
public SessionConfig setOnEvent(Consumer<SessionEvent> onEvent) {
this.onEvent = onEvent;
return this;
}
/**
* Gets the slash commands registered for this session.
*
* @return the list of command definitions, or {@code null}
*/
public List<CommandDefinition> getCommands() {
return commands == null ? null : Collections.unmodifiableList(commands);
}
/**
* Sets slash commands registered for this session.
* <p>
* When the CLI has a TUI, each command appears as {@code /name} for the user to
* invoke. The handler is called when the user executes the command.
*
* @param commands
* the list of command definitions
* @return this config instance for method chaining
* @see CommandDefinition
*/
public SessionConfig setCommands(List<CommandDefinition> commands) {
this.commands = commands;
return this;
}
/**
* Gets the elicitation request handler.
*
* @return the elicitation handler, or {@code null}
*/
public ElicitationHandler getOnElicitationRequest() {
return onElicitationRequest;
}
/**
* Sets a handler for elicitation requests from the server or MCP tools.
* <p>
* When provided, the server will route elicitation requests to this handler and
* report elicitation as a supported capability.
*
* @param onElicitationRequest
* the elicitation handler
* @return this config instance for method chaining
* @see ElicitationHandler
*/
public SessionConfig setOnElicitationRequest(ElicitationHandler onElicitationRequest) {
this.onElicitationRequest = onElicitationRequest;
return this;
}
/**
* Gets the GitHub token for per-session authentication.
*
* @return the GitHub token, or {@code null} if not set
* @since 1.3.0
*/
public String getGitHubToken() {
return gitHubToken;
}
/**
* Sets the GitHub token for per-session authentication.
* <p>
* When provided, the runtime resolves this token into a full GitHub identity
* and stores it on the session for content exclusion, model routing, and quota
* checks.
*
* @param gitHubToken
* the GitHub token for per-session authentication
* @return this config instance for method chaining
* @since 1.3.0
*/
public SessionConfig setGitHubToken(String gitHubToken) {
this.gitHubToken = gitHubToken;
return this;
}
/**
* Creates a shallow clone of this {@code SessionConfig} instance.
* <p>
* Mutable collection properties are copied into new collection instances so
* that modifications to those collections on the clone do not affect the
* original. Other reference-type properties (like provider configuration,
* system messages, hooks, infinite session configuration, and handlers) are not
* deep-cloned; the original and the clone will share those objects.
*
* @return a clone of this config instance
*/
@Override
public SessionConfig clone() {
SessionConfig copy = new SessionConfig();
copy.sessionId = this.sessionId;
copy.clientName = this.clientName;
copy.model = this.model;
copy.reasoningEffort = this.reasoningEffort;
copy.tools = this.tools != null ? new ArrayList<>(this.tools) : null;
copy.systemMessage = this.systemMessage;
copy.availableTools = this.availableTools != null ? new ArrayList<>(this.availableTools) : null;
copy.excludedTools = this.excludedTools != null ? new ArrayList<>(this.excludedTools) : null;
copy.provider = this.provider;
copy.onPermissionRequest = this.onPermissionRequest;
copy.onUserInputRequest = this.onUserInputRequest;
copy.hooks = this.hooks;
copy.workingDirectory = this.workingDirectory;
copy.streaming = this.streaming;
copy.includeSubAgentStreamingEvents = this.includeSubAgentStreamingEvents;
copy.mcpServers = this.mcpServers != null ? new java.util.HashMap<>(this.mcpServers) : null;
copy.customAgents = this.customAgents != null ? new ArrayList<>(this.customAgents) : null;
copy.defaultAgent = this.defaultAgent;
copy.agent = this.agent;
copy.infiniteSessions = this.infiniteSessions;
copy.skillDirectories = this.skillDirectories != null ? new ArrayList<>(this.skillDirectories) : null;
copy.disabledSkills = this.disabledSkills != null ? new ArrayList<>(this.disabledSkills) : null;
copy.configDir = this.configDir;
copy.enableConfigDiscovery = this.enableConfigDiscovery;
copy.modelCapabilities = this.modelCapabilities;
copy.onEvent = this.onEvent;
copy.commands = this.commands != null ? new ArrayList<>(this.commands) : null;
copy.onElicitationRequest = this.onElicitationRequest;
copy.gitHubToken = this.gitHubToken;
return copy;
}
}