Class SessionConfig

java.lang.Object
com.github.copilot.rpc.SessionConfig
public class SessionConfig extends Object
Configuration for creating a new Copilot session.

This class provides options for customizing session behavior, including model selection, tool registration, system message customization, and more. All setter methods return this for method chaining.

Example Usage

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();
Since:
1.0.0
See Also:

  • Constructor Details

    • SessionConfig

      public SessionConfig()

  • Method Details

    • getSessionId

      public String getSessionId()
      Gets the custom session ID.
      Returns:
      the session ID, or null to generate automatically

    • setSessionId

      public SessionConfig setSessionId(String sessionId)
      Sets a custom session ID.

      If not provided, a unique session ID will be generated automatically.

      Parameters:
      sessionId - the custom session ID
      Returns:
      this config instance for method chaining

    • getName

      public String getName()
      Gets the create-time session name.
      Returns:
      the session name, or null if the session is unnamed

    • setName

      public SessionConfig setName(String name)
      Names the session at creation, as session.name.set would, and is validated the same way: non-empty, no leading or trailing whitespace, at most 100 UTF-16 units, no control characters, and no double quotes. A name also makes the session persist from the start, so it can be listed and resumed without ever running a turn. Local sessions only: cloud creation rejects it.
      Parameters:
      name - the session name
      Returns:
      this config instance for method chaining

    • getClientName

      public String getClientName()
      Gets the client name used to identify the application using the SDK.
      Returns:
      the client name, or null if not set

    • setClientName

      public SessionConfig setClientName(String clientName)
      Sets the client name to identify the application using the SDK.

      This value is included in the User-Agent header for API requests.

      Parameters:
      clientName - the client name
      Returns:
      this config instance for method chaining

    • getModel

      public String getModel()
      Gets the AI model to use.
      Returns:
      the model name

    • setModel

      public SessionConfig setModel(String model)
      Sets the AI model to use for this session.

      Examples: "gpt-5", "claude-sonnet-4.5", "o3-mini".

      Parameters:
      model - the model name
      Returns:
      this config instance for method chaining

    • getReasoningEffort

      public String getReasoningEffort()
      Gets the reasoning effort level.
      Returns:
      the reasoning effort level ("low", "medium", "high", "xhigh", or "max")

    • setReasoningEffort

      public SessionConfig setReasoningEffort(String reasoningEffort)
      Sets the reasoning effort level for models that support it.

      Valid values: "low", "medium", "high", "xhigh", "max". Only applies to models where capabilities.supports.reasoningEffort is true.

      Parameters:
      reasoningEffort - the reasoning effort level
      Returns:
      this config instance for method chaining

    • getReasoningSummary

      public String getReasoningSummary()
      Gets the reasoning summary mode.
      Returns:
      the reasoning summary mode ("none", "concise", or "detailed")

    • setReasoningSummary

      public SessionConfig setReasoningSummary(String reasoningSummary)
      Sets the reasoning summary mode for models that support configurable reasoning summaries. Use "none" to suppress summary output regardless of whether reasoning is enabled.
      Parameters:
      reasoningSummary - the reasoning summary mode
      Returns:
      this config instance for method chaining

    • getContextTier

      public String getContextTier()
      Gets the context window tier.
      Returns:
      the context window tier ("default" or "long_context")

    • setContextTier

      public SessionConfig setContextTier(String contextTier)
      Sets the context window tier for models that support it. Use "long_context" to pin the session to the long-context tier; omit or use "default" otherwise.
      Parameters:
      contextTier - the context window tier
      Returns:
      this config instance for method chaining

    • getAskUserVariant

      public AskUserVariant getAskUserVariant()
      Gets the experience used by the built-in ask_user tool.
      Returns:
      the ask-user variant, or null to use the legacy experience

    • setAskUserVariant

      public SessionConfig setAskUserVariant(AskUserVariant askUserVariant)
      Sets the model-facing shape of the built-in ask_user tool.

      When unset, the option is omitted and the legacy shape is used. Set an elicitation handler when selecting AskUserVariant.ELICITATION.

      Parameters:
      askUserVariant - the ask-user variant
      Returns:
      this config instance for method chaining

    • getTools

      public List<ToolDefinition> getTools()
      Gets the custom tools for this session.
      Returns:
      the list of tool definitions

    • setTools

      public SessionConfig setTools(List<ToolDefinition> tools)
      Sets custom tools that the assistant can invoke during the session.

      Tools allow the assistant to call back into your application to perform actions or retrieve information.

      Parameters:
      tools - the list of tool definitions
      Returns:
      this config instance for method chaining
      See Also:

    • getSystemMessage

      public SystemMessageConfig getSystemMessage()
      Gets the system message configuration.
      Returns:
      the system message config

    • setSystemMessage

      public SessionConfig setSystemMessage(SystemMessageConfig systemMessage)
      Sets the system message configuration.

      The system message controls the behavior and personality of the assistant. Use SystemMessageMode.APPEND to add instructions while preserving default behavior, or SystemMessageMode.REPLACE to fully customize.

      Parameters:
      systemMessage - the system message configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getAvailableTools

      public List<String> getAvailableTools()
      Gets the list of allowed tool names.
      Returns:
      the list of available tool names

    • setAvailableTools

      public SessionConfig setAvailableTools(List<String> availableTools)
      Sets the list of tool names that are allowed in this session.

      When specified, only tools in this list will be available to the assistant.

      Parameters:
      availableTools - the list of allowed tool names
      Returns:
      this config instance for method chaining

    • getExcludedTools

      public List<String> getExcludedTools()
      Gets the list of excluded tool names.
      Returns:
      the list of excluded tool names

    • setExcludedTools

      public SessionConfig setExcludedTools(List<String> excludedTools)
      Sets the list of tool names to exclude from this session.

      Tools in this list will not be available to the assistant.

      Parameters:
      excludedTools - the list of tool names to exclude
      Returns:
      this config instance for method chaining

    • getExcludedBuiltInAgents

      public List<String> getExcludedBuiltInAgents()
      Gets the built-in agent names excluded from this session.
      Returns:
      the list of excluded built-in agent names

    • setExcludedBuiltInAgents

      public SessionConfig setExcludedBuiltInAgents(List<String> excludedBuiltInAgents)
      Sets the built-in agent names to exclude from this session.

      Excluded built-in agents are hidden from discovery and cannot be selected or invoked unless a custom agent with the same name is configured.

      Parameters:
      excludedBuiltInAgents - the built-in agent names to exclude
      Returns:
      this config instance for method chaining

    • getProvider

      public ProviderConfig getProvider()
      Gets the custom API provider configuration.
      Returns:
      the provider configuration

    • setProvider

      public SessionConfig setProvider(ProviderConfig provider)
      Sets a custom API provider for BYOK (Bring Your Own Key) scenarios.

      This allows using your own OpenAI, Azure OpenAI, or other compatible API endpoints instead of the default Copilot backend.

      Parameters:
      provider - the provider configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getCapi

      public CapiSessionOptions getCapi()
      Gets the CAPI provider-scoped session options.
      Returns:
      the CAPI session options

    • setCapi

      public SessionConfig setCapi(CapiSessionOptions capi)
      Sets CAPI provider-scoped session options.

      Use CapiSessionOptions.setEnableWebSocketResponses(Boolean) with false to force the HTTP Responses transport instead of the default CAPI Responses API WebSocket transport.

      Parameters:
      capi - the CAPI session options
      Returns:
      this config instance for method chaining
      See Also:

    • getProviders

      @CopilotExperimental public List<NamedProviderConfig> getProviders()
      Gets the named BYOK provider connections.
      Returns:
      the named provider connections, or null if not set

    • setProviders

      @CopilotExperimental public SessionConfig setProviders(List<NamedProviderConfig> providers)
      Sets the named BYOK provider connections (additive multi-provider registry).

      Unlike setProvider(ProviderConfig), these do not switch the whole session to BYOK; they are exposed alongside the default Copilot routing. Attach models referencing these connections with setModels(List).

      Parameters:
      providers - the named provider connections
      Returns:
      this config instance for method chaining
      See Also:

    • getModels

      @CopilotExperimental public List<ProviderModelConfig> getModels()
      Gets the BYOK model definitions.
      Returns:
      the model definitions, or null if not set

    • setModels

      @CopilotExperimental public SessionConfig setModels(List<ProviderModelConfig> models)
      Sets the BYOK model definitions, each referencing a named provider supplied via setProviders(List).
      Parameters:
      models - the model definitions
      Returns:
      this config instance for method chaining
      See Also:

    • getEnableSessionTelemetry

      public Optional<Boolean> getEnableSessionTelemetry()
      Enables or disables internal session telemetry for this session. When false, disables session telemetry. When unset (the default) or true, telemetry is enabled for GitHub-authenticated sessions. When a custom ProviderConfig (BYOK) is configured, session telemetry is always disabled regardless of this setting. This is independent of CopilotClientOptions.TelemetryConfig, which configures OpenTelemetry export for observability.
      Returns:
      an Optional containing whether session telemetry is enabled, or Optional.empty() for the default

    • setEnableSessionTelemetry

      public SessionConfig setEnableSessionTelemetry(boolean enableSessionTelemetry)
      Enables or disables internal session telemetry for this session. When false, disables session telemetry. When unset (the default) or true, telemetry is enabled for GitHub-authenticated sessions. When a custom ProviderConfig (BYOK) is configured, session telemetry is always disabled regardless of this setting.
      Parameters:
      enableSessionTelemetry - whether to enable session telemetry
      Returns:
      this config instance for method chaining

    • clearEnableSessionTelemetry

      public SessionConfig clearEnableSessionTelemetry()
      Clears the enableSessionTelemetry setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getEnableCitations

      @CopilotExperimental public Optional<Boolean> getEnableCitations()
      Gets whether native model citations are enabled.
      Returns:
      an Optional containing whether citations are enabled, or Optional.empty() for the default

    • setEnableCitations

      @CopilotExperimental public SessionConfig setEnableCitations(boolean enableCitations)
      Enables or disables native model citations for supported providers.
      Parameters:
      enableCitations - whether to enable citations
      Returns:
      this config instance for method chaining

    • clearEnableCitations

      @CopilotExperimental public SessionConfig clearEnableCitations()
      Clears the enableCitations setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getEnableFileChangeTracking

      public Optional<Boolean> getEnableFileChangeTracking()
      Gets whether file change tracking is enabled for rewind and cumulative session diff.
      Returns:
      an Optional containing the setting, or Optional.empty() for the default

    • setEnableFileChangeTracking

      public SessionConfig setEnableFileChangeTracking(boolean enableFileChangeTracking)
      Enables or disables file change tracking from the first turn.
      Parameters:
      enableFileChangeTracking - whether to enable file change tracking
      Returns:
      this config instance for method chaining

    • clearEnableFileChangeTracking

      public SessionConfig clearEnableFileChangeTracking()
      Clears the file change tracking setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getSessionLimits

      @CopilotExperimental public SessionLimitsConfig getSessionLimits()
      Gets the limits for this session's current accounting window.
      Returns:
      the session limits, or null if not set

    • setSessionLimits

      @CopilotExperimental public SessionConfig setSessionLimits(SessionLimitsConfig sessionLimits)
      Sets limits for this session's current accounting window.
      Parameters:
      sessionLimits - the session limits
      Returns:
      this config instance for method chaining

    • clearSessionLimits

      @CopilotExperimental public SessionConfig clearSessionLimits()
      Clears the sessionLimits setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getEnableExperimentalMode

      public Optional<Boolean> getEnableExperimentalMode()
      Controls whether the session enables experimental features.
      Returns:
      true when experimental features are enabled, false when they are disabled, or empty to use the mode-specific default

    • setEnableExperimentalMode

      public SessionConfig setEnableExperimentalMode(boolean enableExperimentalMode)
      Controls whether the session enables experimental features.
      Parameters:
      enableExperimentalMode - true to enable experimental features; false to disable them
      Returns:
      this config instance for method chaining

    • clearEnableExperimentalMode

      public SessionConfig clearEnableExperimentalMode()
      Clears the enableExperimentalMode setting. In EMPTY mode this defaults to false; otherwise the runtime decides.
      Returns:
      this instance for method chaining

    • getSkipCustomInstructions

      public Optional<Boolean> getSkipCustomInstructions()
      Gets whether custom instruction file loading is suppressed.
      Returns:
      true to suppress, or empty if not explicitly set
      Since:
      1.3.0

    • setSkipCustomInstructions

      public SessionConfig setSkipCustomInstructions(boolean skipCustomInstructions)
      Sets whether to suppress loading of custom instruction files (e.g. .github/copilot-instructions.md, AGENTS.md) from the working directory.

      This option is sent to the server via a session.options.update JSON-RPC call immediately after session creation. In EMPTY mode the default is true (skip); in COPILOT_CLI mode the value is forwarded only when explicitly set.

      Parameters:
      skipCustomInstructions - whether to skip custom instructions
      Returns:
      this config instance for method chaining
      Since:
      1.3.0

    • clearSkipCustomInstructions

      public SessionConfig clearSkipCustomInstructions()
      Clears the skipCustomInstructions setting.
      Returns:
      this instance for method chaining
      Since:
      1.3.0

    • getCustomAgentsLocalOnly

      public Optional<Boolean> getCustomAgentsLocalOnly()
      Gets whether custom-agent discovery is restricted to local only.
      Returns:
      true for local only, or empty if not explicitly set
      Since:
      1.3.0

    • setCustomAgentsLocalOnly

      public SessionConfig setCustomAgentsLocalOnly(boolean customAgentsLocalOnly)
      Sets whether custom-agent discovery is restricted to the session's local working directory (no organisation-level discovery).

      This option is sent with the initial create request and maintained via session.options.update. In EMPTY mode the default is true (local only); in COPILOT_CLI mode the value is forwarded only when explicitly set.

      Parameters:
      customAgentsLocalOnly - whether to restrict to local agents
      Returns:
      this config instance for method chaining
      Since:
      1.3.0

    • clearCustomAgentsLocalOnly

      public SessionConfig clearCustomAgentsLocalOnly()
      Clears the customAgentsLocalOnly setting.
      Returns:
      this instance for method chaining
      Since:
      1.3.0

    • getCoauthorEnabled

      public Optional<Boolean> getCoauthorEnabled()
      Gets whether the runtime may append a Co-authored-by trailer.
      Returns:
      the coauthor enabled flag, or empty if not explicitly set
      Since:
      1.3.0

    • setCoauthorEnabled

      public SessionConfig setCoauthorEnabled(boolean coauthorEnabled)
      Sets whether the runtime is allowed to append a Co-authored-by trailer when it commits on behalf of the user.

      This option is sent to the server via a session.options.update JSON-RPC call immediately after session creation. In EMPTY mode the default is false (disabled); in COPILOT_CLI mode the value is forwarded only when explicitly set.

      Parameters:
      coauthorEnabled - whether coauthor is enabled
      Returns:
      this config instance for method chaining
      Since:
      1.3.0

    • clearCoauthorEnabled

      public SessionConfig clearCoauthorEnabled()
      Clears the coauthorEnabled setting.
      Returns:
      this instance for method chaining
      Since:
      1.3.0

    • getManageScheduleEnabled

      public Optional<Boolean> getManageScheduleEnabled()
      Gets whether the manage_schedule tool is enabled.
      Returns:
      the manage schedule flag, or empty if not explicitly set
      Since:
      1.3.0

    • setManageScheduleEnabled

      public SessionConfig setManageScheduleEnabled(boolean manageScheduleEnabled)
      Sets whether to enable the manage_schedule tool (host scheduler integration).

      This option is sent to the server via a session.options.update JSON-RPC call immediately after session creation. In EMPTY mode the default is false (disabled); in COPILOT_CLI mode the value is forwarded only when explicitly set.

      Parameters:
      manageScheduleEnabled - whether manage schedule is enabled
      Returns:
      this config instance for method chaining
      Since:
      1.3.0

    • clearManageScheduleEnabled

      public SessionConfig clearManageScheduleEnabled()
      Clears the manageScheduleEnabled setting.
      Returns:
      this instance for method chaining
      Since:
      1.3.0

    • getOnPermissionRequest

      public PermissionHandler getOnPermissionRequest()
      Gets the permission request handler.
      Returns:
      the permission handler

    • setOnPermissionRequest

      public SessionConfig setOnPermissionRequest(PermissionHandler onPermissionRequest)
      Sets a handler for permission requests from the assistant.

      When the assistant needs permission to perform certain actions, this handler will be invoked to approve or deny the request.

      Parameters:
      onPermissionRequest - the permission handler
      Returns:
      this config instance for method chaining
      See Also:

    • getOnMcpAuthRequest

      public McpAuthHandler getOnMcpAuthRequest()
      Gets the MCP OAuth request handler.
      Returns:
      the handler, or null if not set

    • setOnMcpAuthRequest

      public SessionConfig setOnMcpAuthRequest(McpAuthHandler onMcpAuthRequest)
      Sets the MCP OAuth request handler.

      When provided, the SDK can satisfy MCP server OAuth requests with host-provided token data or cancellation.

      Parameters:
      onMcpAuthRequest - the handler
      Returns:
      this config instance for method chaining

    • getOnUserInputRequest

      public UserInputHandler getOnUserInputRequest()
      Gets the user input request handler.
      Returns:
      the user input handler

    • setOnUserInputRequest

      public SessionConfig setOnUserInputRequest(UserInputHandler onUserInputRequest)
      Sets a handler for user input requests from the agent.

      When provided, enables the legacy question-and-answer form of the ask_user tool. Use an elicitation handler with AskUserVariant.ELICITATION.

      Parameters:
      onUserInputRequest - the user input handler
      Returns:
      this config instance for method chaining
      See Also:

    • getHooks

      public SessionHooks getHooks()
      Gets the hook handlers configuration.
      Returns:
      the session hooks

    • setHooks

      public SessionConfig setHooks(SessionHooks hooks)
      Sets hook handlers for session lifecycle events.

      Hooks allow you to intercept and modify tool execution behavior.

      Parameters:
      hooks - the hooks configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getWorkingDirectory

      public String getWorkingDirectory()
      Gets the working directory for the session.
      Returns:
      the working directory path

    • setWorkingDirectory

      public SessionConfig setWorkingDirectory(String workingDirectory)
      Sets the working directory for the session.
      Parameters:
      workingDirectory - the working directory path
      Returns:
      this config instance for method chaining

    • getAdditionalDirectories

      public List<String> getAdditionalDirectories()
      Gets the directories the agent may access beyond the working directory.
      Returns:
      the additional directory paths

    • setAdditionalDirectories

      public SessionConfig setAdditionalDirectories(List<String> additionalDirectories)
      Sets directories the agent may access beyond the working directory.
      Parameters:
      additionalDirectories - the additional directory paths
      Returns:
      this config instance for method chaining

    • isStreaming

      public boolean isStreaming()
      Returns whether streaming is enabled.
      Returns:
      true if streaming is enabled

    • setStreaming

      public SessionConfig setStreaming(boolean streaming)
      Sets whether to enable streaming of response chunks.

      When enabled, the session will emit AssistantMessageDeltaEvent events as the response is generated, allowing for real-time display of partial responses.

      Parameters:
      streaming - true to enable streaming
      Returns:
      this config instance for method chaining

    • getMcpServers

      public Map<String, McpServerConfig> getMcpServers()
      Gets the MCP server configurations.
      Returns:
      the MCP servers map

    • setMcpServers

      public SessionConfig setMcpServers(Map<String, McpServerConfig> mcpServers)
      Sets MCP (Model Context Protocol) server configurations.

      MCP servers extend the assistant's capabilities by providing additional context sources and tools.

      Parameters:
      mcpServers - the MCP servers configuration map
      Returns:
      this config instance for method chaining

    • getDiagnostics

      public DiagnosticsConfiguration getDiagnostics()
      Gets the session-scoped diagnostics configuration.
      Returns:
      the diagnostic level, or null when diagnostics are disabled

    • setDiagnostics

      public SessionConfig setDiagnostics(DiagnosticsConfiguration diagnostics)
      Sets the session-scoped diagnostics configuration. Diagnostics are off by default. Debug and trace entries can contain MCP payloads, tool arguments, paths, and server stderr. Do not upload entries as telemetry or export them without deliberate host action.
      Parameters:
      diagnostics - the diagnostic level
      Returns:
      this config for method chaining

    • getMcpOAuthTokenStorage

      public String getMcpOAuthTokenStorage()
      Gets the MCP OAuth token storage mode.
      Returns:
      the storage mode, or null if not set

    • setMcpOAuthTokenStorage

      public SessionConfig setMcpOAuthTokenStorage(String mcpOAuthTokenStorage)
      Sets the MCP OAuth token storage mode.

      Controls how MCP OAuth tokens are stored for this session:

      • "persistent" — tokens are stored in the OS keychain (shared across sessions)
      • "in-memory" — tokens are stored in memory and discarded when the session ends
      If not set and the client is in EMPTY mode, the SDK defaults to "in-memory" for safe multitenant behavior. In other modes this field is left unset.
      Parameters:
      mcpOAuthTokenStorage - the storage mode
      Returns:
      this config instance for method chaining

    • getAuthClientIdMetadataUrl

      public String getAuthClientIdMetadataUrl()
      Gets the OAuth Client ID Metadata Document URL identifying the host.
      Returns:
      the metadata URL, or null if not set

    • setAuthClientIdMetadataUrl

      public SessionConfig setAuthClientIdMetadataUrl(String authClientIdMetadataUrl)
      Sets the OAuth Client ID Metadata Document URL identifying the host for MCP authorization. When unset, no host identity is supplied.
      Parameters:
      authClientIdMetadataUrl - the metadata URL
      Returns:
      this config instance for method chaining

    • getCustomAgents

      public List<CustomAgentConfig> getCustomAgents()
      Gets the custom agent configurations.
      Returns:
      the list of custom agent configurations

    • setCustomAgents

      public SessionConfig setCustomAgents(List<CustomAgentConfig> customAgents)
      Sets custom agent configurations.

      Custom agents allow extending the assistant with specialized behaviors and capabilities.

      Parameters:
      customAgents - the list of custom agent configurations
      Returns:
      this config instance for method chaining
      See Also:

    • getDefaultAgent

      public DefaultAgentConfig getDefaultAgent()
      Gets the default agent configuration.
      Returns:
      the default agent configuration, or null if not set

    • setDefaultAgent

      public SessionConfig setDefaultAgent(DefaultAgentConfig defaultAgent)
      Sets the default agent configuration.

      Use DefaultAgentConfig.setExcludedTools(List) to hide specific tools from the default agent while keeping them available to custom sub-agents.

      Parameters:
      defaultAgent - the default agent configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getAgent

      public String getAgent()
      Gets the name of the custom agent to activate at session start.
      Returns:
      the agent name, or null if not set

    • setAgent

      public SessionConfig setAgent(String agent)
      Sets the name of the custom agent to activate when the session starts.

      Must match the name of one of the agents in setCustomAgents(List).

      Parameters:
      agent - the agent name to pre-select
      Returns:
      this config instance for method chaining

    • getInfiniteSessions

      public InfiniteSessionConfig getInfiniteSessions()
      Gets the infinite sessions configuration.
      Returns:
      the infinite sessions config

    • setInfiniteSessions

      public SessionConfig setInfiniteSessions(InfiniteSessionConfig infiniteSessions)
      Sets the infinite session configuration for persistent workspaces and automatic compaction.

      When enabled (default), sessions automatically manage context limits and persist state to a workspace directory. The workspace contains checkpoints/, plan.md, and files/ subdirectories.

      Parameters:
      infiniteSessions - the infinite sessions configuration
      Returns:
      this config instance for method chaining
      See Also:

    • getSkillDirectories

      public List<String> getSkillDirectories()
      Gets explicit discovery-only skill roots, not general filesystem grants. Available without configuration discovery, subject to skill/managed disables. Relative paths resolve once when supplied against the request's effective working directory; retained roots do not move when it changes. Null and omission are equivalent; an empty list clears only the SDK contribution.
      Returns:
      the list of skill directory paths

    • setSkillDirectories

      public SessionConfig setSkillDirectories(List<String> skillDirectories)
      Sets the skill directories for loading custom skills.

      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.

      Parameters:
      skillDirectories - the list of skill directory paths
      Returns:
      this config instance for method chaining

    • getAgentDirectories

      public List<String> getAgentDirectories()
      Gets explicit discovery-only agent roots, separate from custom agent objects. No general filesystem grant. Available without configuration discovery, subject to source/managed disables. Relative paths resolve once when supplied against the request's effective working directory; retained roots do not move. Null and omission are equivalent; an empty list clears only the SDK contribution.
      Returns:
      the agent directory paths

    • setAgentDirectories

      public SessionConfig setAgentDirectories(List<String> agentDirectories)
      Sets explicit discovery-only agent roots. See getAgentDirectories().
      Parameters:
      agentDirectories - the agent directory paths
      Returns:
      this config for method chaining

    • getHookDirectories

      public List<String> getHookDirectories()
      Gets explicit discovery-only file-hook roots, separate from callback hooks. No general filesystem grant. Available without configuration discovery or file-hook enablement (repository-origin hooks only), subject to hook/managed disables. Relative paths resolve once when supplied against the request's effective working directory; retained roots do not move. Null and omission are equivalent; an empty list clears only the SDK contribution.
      Returns:
      the file-hook directory paths

    • setHookDirectories

      public SessionConfig setHookDirectories(List<String> hookDirectories)
      Sets explicit discovery-only file-hook roots. See getHookDirectories().
      Parameters:
      hookDirectories - the file-hook directory paths
      Returns:
      this config for method chaining

    • getIncludedBuiltinSkills

      public List<String> getIncludedBuiltinSkills()
      Gets the runtime-bundled skill allowlist.
      Returns:
      the built-in skill names, or null when unspecified

    • setIncludedBuiltinSkills

      public SessionConfig setIncludedBuiltinSkills(List<String> includedBuiltinSkills)
      Sets the runtime-bundled skill allowlist. In empty mode, omitting this option excludes all built-in skills; specifying names opts those built-ins back in.
      Parameters:
      includedBuiltinSkills - the built-in skill names to allow
      Returns:
      this config instance for method chaining

    • getInstructionDirectories

      public List<String> getInstructionDirectories()
      Gets explicit discovery-only instruction roots using existing SDK formats. No general filesystem grant. Available without configuration discovery, subject to instruction/managed disables. Relative paths resolve once when supplied against the request's effective working directory; retained roots do not move. Null and omission are equivalent; an empty list clears only the SDK contribution.
      Returns:
      the list of instruction directory paths

    • setInstructionDirectories

      public SessionConfig setInstructionDirectories(List<String> instructionDirectories)
      Sets additional directories to search for custom instruction files.
      Parameters:
      instructionDirectories - the list of instruction directory paths
      Returns:
      this config instance for method chaining

    • getPluginDirectories

      public List<String> getPluginDirectories()
      Gets the plugin directories to load Open Plugin definitions from.
      Returns:
      the list of plugin directory paths

    • setPluginDirectories

      public SessionConfig setPluginDirectories(List<String> pluginDirectories)
      Sets the plugin directories to load Open Plugin definitions from.
      Parameters:
      pluginDirectories - the list of plugin directory paths
      Returns:
      this config instance for method chaining

    • getLargeOutput

      public LargeToolOutputConfig getLargeOutput()
      Gets the configuration for large tool output handling.
      Returns:
      the large output config, or null for default

    • setLargeOutput

      public SessionConfig setLargeOutput(LargeToolOutputConfig largeOutput)
      Sets the configuration for large tool output handling.
      Parameters:
      largeOutput - the large output config
      Returns:
      this config instance for method chaining

    • getToolSearch

      public ToolSearchConfig getToolSearch()
      Gets the tool-search override configuration.
      Returns:
      the tool-search config, or null for the runtime default

    • getImageGeneration

      @CopilotExperimental public ImageGenerationConfig getImageGeneration()
      Gets the non-persisted image generation opt-in.
      Returns:
      the image generation config, or null when unset

    • setImageGeneration

      @CopilotExperimental public SessionConfig setImageGeneration(ImageGenerationConfig imageGeneration)
      Sets the image generation opt-in. Re-supply after runtime restart.
      Parameters:
      imageGeneration - the image generation config
      Returns:
      this config for method chaining

    • setToolSearch

      public SessionConfig setToolSearch(ToolSearchConfig toolSearch)
      Sets the tool-search override configuration. When null, the runtime default tool-search behavior applies.
      Parameters:
      toolSearch - the tool-search config
      Returns:
      this config instance for method chaining

    • getMemory

      public MemoryConfiguration getMemory()
      Gets the configuration for session memory.
      Returns:
      the memory config, or null for default

    • setMemory

      public SessionConfig setMemory(MemoryConfiguration memory)
      Sets the configuration for session memory.
      Parameters:
      memory - the memory config
      Returns:
      this config instance for method chaining

    • getDisabledSkills

      public List<String> getDisabledSkills()
      Gets the disabled skill names.
      Returns:
      the list of disabled skill names

    • setDisabledSkills

      public SessionConfig setDisabledSkills(List<String> disabledSkills)
      Sets the list of skill names to disable.

      Skills in this list will not be applied to the session, even if they are found in the skill directories.

      Parameters:
      disabledSkills - the list of skill names to disable
      Returns:
      this config instance for method chaining

    • getDisabledMcpServers

      public List<String> getDisabledMcpServers()
      Gets exact MCP server names disabled for this session.
      Returns:
      the disabled MCP server names, or null when none are disabled

    • setDisabledMcpServers

      public SessionConfig setDisabledMcpServers(List<String> disabledMcpServers)
      Sets exact MCP server names to disable for this session. Disabled servers are not started or authenticated on create or cold resume; a resident resume cannot stop servers already running.
      Parameters:
      disabledMcpServers - the server names to disable
      Returns:
      this config for method chaining

    • getConfigDirectory

      public String getConfigDirectory()
      Gets the custom configuration directory.
      Returns:
      the config directory path

    • setConfigDirectory

      public SessionConfig setConfigDirectory(String configDirectory)
      Sets a custom configuration directory for the session.

      This allows using a specific directory for session configuration instead of the default location.

      Parameters:
      configDirectory - the configuration directory path
      Returns:
      this config instance for method chaining

    • getEnableConfigDiscovery

      public Optional<Boolean> getEnableConfigDiscovery()
      Gets whether automatic configuration discovery is enabled.
      Returns:
      an Optional containing true to enable discovery or false to disable, or Optional.empty() to use the default behavior

    • setEnableConfigDiscovery

      public SessionConfig setEnableConfigDiscovery(boolean enableConfigDiscovery)
      Enables runtime discovery of supported configuration. Explicitly supplied configuration takes precedence over discovered values.
      Parameters:
      enableConfigDiscovery - true to enable discovery, false to disable
      Returns:
      this config instance for method chaining

    • clearEnableConfigDiscovery

      public SessionConfig clearEnableConfigDiscovery()
      Clears the enableConfigDiscovery setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getSkipEmbeddingRetrieval

      public Optional<Boolean> getSkipEmbeddingRetrieval()
      Gets whether embedding-based retrieval is skipped.
      Returns:
      an Optional containing true to skip embedding retrieval or false to force it, or Optional.empty() to use the default behavior

    • setSkipEmbeddingRetrieval

      public SessionConfig setSkipEmbeddingRetrieval(boolean skipEmbeddingRetrieval)
      Sets whether to skip embedding-based retrieval.
      Parameters:
      skipEmbeddingRetrieval - true to skip embedding retrieval, false to keep it enabled
      Returns:
      this config instance for method chaining

    • clearSkipEmbeddingRetrieval

      public SessionConfig clearSkipEmbeddingRetrieval()
      Clears the skipEmbeddingRetrieval setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getOrganizationCustomInstructions

      public String getOrganizationCustomInstructions()
      Gets the organization-level custom instructions.
      Returns:
      the organization-level custom instructions, or null if not set

    • setOrganizationCustomInstructions

      public SessionConfig setOrganizationCustomInstructions(String organizationCustomInstructions)
      Sets organization-level custom instructions.
      Parameters:
      organizationCustomInstructions - the organization-level custom instructions
      Returns:
      this config instance for method chaining

    • getEnableOnDemandInstructionDiscovery

      public Optional<Boolean> getEnableOnDemandInstructionDiscovery()
      Gets whether on-demand instruction file discovery is enabled.
      Returns:
      an Optional containing true to enable on-demand discovery or false to disable it, or Optional.empty() to use the default behavior

    • setEnableOnDemandInstructionDiscovery

      public SessionConfig setEnableOnDemandInstructionDiscovery(boolean enableOnDemandInstructionDiscovery)
      Sets whether instruction files are discovered on demand.
      Parameters:
      enableOnDemandInstructionDiscovery - true to enable on-demand instruction discovery, false to disable it
      Returns:
      this config instance for method chaining

    • clearEnableOnDemandInstructionDiscovery

      public SessionConfig clearEnableOnDemandInstructionDiscovery()
      Clears the enableOnDemandInstructionDiscovery setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getRefreshCustomInstructions

      public Optional<Boolean> getRefreshCustomInstructions()
      Gets whether to invalidate process-wide instruction discovery caches before constructing the new session.
      Returns:
      an optional flag; false or empty reuses cached discovery

    • setRefreshCustomInstructions

      public SessionConfig setRefreshCustomInstructions(boolean refreshCustomInstructions)
      Sets whether to invalidate process-wide instruction discovery caches before constructing the new session. Defaults to false, reusing cached discovery. Other sessions in this runtime may observe updated instructions on later turns or discovery. This does not watch files or override instruction loading policy.
      Parameters:
      refreshCustomInstructions - true to invalidate caches, false to reuse them
      Returns:
      this config instance for method chaining

    • clearRefreshCustomInstructions

      public SessionConfig clearRefreshCustomInstructions()
      Clears the refreshCustomInstructions setting, restoring default cache reuse.
      Returns:
      this config instance for method chaining

    • getEnableFileHooks

      public Optional<Boolean> getEnableFileHooks()
      Gets whether repository-origin file hooks from .github/hooks/ and trusted repository-configured roots are enabled. Does not control explicit getHookDirectories() or callback hooks.
      Returns:
      an Optional containing true to enable file hooks or false to disable them, or Optional.empty() to use the default behavior

    • setEnableFileHooks

      public SessionConfig setEnableFileHooks(boolean enableFileHooks)
      Controls repository-origin hooks, including accepted startup additional roots. This gate supports live updates. Additional-root eligibility and DISABLE_ADDITIONAL_DIRECTORY_HOOKS remain startup-scoped. Explicit hook directories and callbacks are independent.
      Parameters:
      enableFileHooks - true to enable file hooks, false to disable them
      Returns:
      this config instance for method chaining

    • clearEnableFileHooks

      public SessionConfig clearEnableFileHooks()
      Clears the enableFileHooks setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getEnableHostGitOperations

      public Optional<Boolean> getEnableHostGitOperations()
      Gets whether host git operations are enabled.
      Returns:
      an Optional containing true to enable host git operations or false to disable them, or Optional.empty() to use the default behavior

    • setEnableHostGitOperations

      public SessionConfig setEnableHostGitOperations(boolean enableHostGitOperations)
      Sets whether git operations on the host filesystem are enabled.
      Parameters:
      enableHostGitOperations - true to enable host git operations, false to disable them
      Returns:
      this config instance for method chaining

    • clearEnableHostGitOperations

      public SessionConfig clearEnableHostGitOperations()
      Clears the enableHostGitOperations setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getEnableSessionStore

      public Optional<Boolean> getEnableSessionStore()
      Gets whether the cross-session store is enabled.
      Returns:
      an Optional containing true to enable the session store or false to disable it, or Optional.empty() to use the default behavior

    • setEnableSessionStore

      public SessionConfig setEnableSessionStore(boolean enableSessionStore)
      Sets whether the cross-session store is enabled.
      Parameters:
      enableSessionStore - true to enable the session store, false to disable it
      Returns:
      this config instance for method chaining

    • clearEnableSessionStore

      public SessionConfig clearEnableSessionStore()
      Clears the enableSessionStore setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getEnableGitHubCacheStore

      public Optional<Boolean> getEnableGitHubCacheStore()
      Gets whether the read-only GitHub cache store is requested.
      Returns:
      an Optional containing true to request the github-cache-store capability or false to decline it, or Optional.empty() to use the default behavior (disabled)

    • setEnableGitHubCacheStore

      public SessionConfig setEnableGitHubCacheStore(boolean enableGitHubCacheStore)
      Sets whether the read-only GitHub cache store is requested.

      The runtime registers the github_sql tool only when its GITHUB_CACHE_STORE feature flag is also on.

      Parameters:
      enableGitHubCacheStore - true to request the github-cache-store capability, false to decline it
      Returns:
      this config instance for method chaining

    • clearEnableGitHubCacheStore

      public SessionConfig clearEnableGitHubCacheStore()
      Clears the enableGitHubCacheStore setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getEnableSkills

      public Optional<Boolean> getEnableSkills()
      Gets whether skill loading is enabled.
      Returns:
      an Optional containing true to enable skill loading or false to disable it, or Optional.empty() to use the default behavior

    • setEnableSkills

      public SessionConfig setEnableSkills(boolean enableSkills)
      Sets whether skill loading is enabled.
      Parameters:
      enableSkills - true to enable skill loading, false to disable it
      Returns:
      this config instance for method chaining

    • clearEnableSkills

      public SessionConfig clearEnableSkills()
      Clears the enableSkills setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getSkillProvider

      @CopilotExperimental public SkillProvider getSkillProvider()
      Gets the session-scoped skill provider.
      Returns:
      the skill provider, or null when not configured

    • setSkillProvider

      @CopilotExperimental public SessionConfig setSkillProvider(SkillProvider skillProvider)
      Sets the session-scoped skill provider.

      Re-supply this provider when resuming a session. Skill providers are not supported for cloud sessions.

      Parameters:
      skillProvider - the skill provider to expose to the runtime
      Returns:
      this config instance for method chaining

    • getEmbeddingCacheStorage

      public String getEmbeddingCacheStorage()
      Gets the embedding cache storage mode.
      Returns:
      the embedding cache storage mode ("persistent" or "in-memory"), or null to use the default behavior

    • setEmbeddingCacheStorage

      public SessionConfig setEmbeddingCacheStorage(String embeddingCacheStorage)
      Sets the embedding cache storage mode.
      Parameters:
      embeddingCacheStorage - "persistent" to persist embeddings across sessions, or "in-memory" for session-scoped storage
      Returns:
      this config instance for method chaining

    • clearEmbeddingCacheStorage

      public SessionConfig clearEmbeddingCacheStorage()
      Clears the embeddingCacheStorage setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getIncludeSubAgentStreamingEvents

      public Optional<Boolean> getIncludeSubAgentStreamingEvents()
      Gets whether sub-agent streaming events are included.
      Returns:
      an Optional containing true to include sub-agent streaming events or false to suppress them, or Optional.empty() to use the runtime default

    • setIncludeSubAgentStreamingEvents

      public SessionConfig setIncludeSubAgentStreamingEvents(boolean includeSubAgentStreamingEvents)
      Sets whether to include sub-agent streaming events in the event stream.

      When true, streaming delta events from sub-agents (e.g., assistant.message_delta with agentId set) are forwarded to this connection. When false, only non-streaming sub-agent events and subagent.* lifecycle events are forwarded; streaming deltas from sub-agents are suppressed. Default: true.

      Parameters:
      includeSubAgentStreamingEvents - true to include streaming events, false to suppress
      Returns:
      this config instance for method chaining

    • clearIncludeSubAgentStreamingEvents

      public SessionConfig clearIncludeSubAgentStreamingEvents()
      Clears the includeSubAgentStreamingEvents setting, reverting to the default behavior.
      Returns:
      this instance for method chaining

    • getModelCapabilities

      public ModelCapabilitiesOverride getModelCapabilities()
      Gets the model capabilities override.
      Returns:
      the model capabilities override, or null if not set

    • setModelCapabilities

      public SessionConfig setModelCapabilities(ModelCapabilitiesOverride modelCapabilities)
      Sets per-property overrides for model capabilities, deep-merged over runtime defaults.

      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.

      Parameters:
      modelCapabilities - the model capabilities override
      Returns:
      this config instance for method chaining
      See Also:

    • getOnEvent

      public Consumer<SessionEvent> getOnEvent()
      Gets the event handler registered before the session.create RPC is issued.
      Returns:
      the event handler, or null if not set

    • setOnEvent

      public SessionConfig setOnEvent(Consumer<SessionEvent> onEvent)
      Sets an event handler that is registered on the session before the session.create RPC is issued.

      Equivalent to calling CopilotSession.on(Consumer) immediately after creation, but executes earlier in the lifecycle so no events are missed. Using this property rather than CopilotSession.on() guarantees that early events emitted by the CLI during session creation (e.g. session.start) are delivered to the handler.

      Parameters:
      onEvent - the event handler to register before session creation
      Returns:
      this config instance for method chaining

    • getCommands

      public List<CommandDefinition> getCommands()
      Gets the slash commands registered for this session.
      Returns:
      the list of command definitions, or null

    • setCommands

      public SessionConfig setCommands(List<CommandDefinition> commands)
      Sets slash commands registered for this session.

      When the CLI has a TUI, each command appears as /name for the user to invoke. The handler is called when the user executes the command.

      Parameters:
      commands - the list of command definitions
      Returns:
      this config instance for method chaining
      See Also:

    • getOnElicitationRequest

      public ElicitationHandler getOnElicitationRequest()
      Gets the elicitation request handler.
      Returns:
      the elicitation handler, or null

    • setOnElicitationRequest

      public SessionConfig setOnElicitationRequest(ElicitationHandler onElicitationRequest)
      Sets a handler for elicitation requests from the server or MCP tools.

      When provided, the server will route elicitation requests to this handler and report elicitation as a supported capability.

      Parameters:
      onElicitationRequest - the elicitation handler
      Returns:
      this config instance for method chaining
      See Also:

    • isEnableMcpApps

      public boolean isEnableMcpApps()
      Returns whether MCP Apps (SEP-1865) UI passthrough is enabled on this session.
      Returns:
      true if the consumer has opted into MCP Apps, otherwise false
      See Also:

    • setEnableMcpApps

      public SessionConfig setEnableMcpApps(boolean enableMcpApps)
      Enables MCP Apps (SEP-1865) UI passthrough on this session.

      When true and the runtime has MCP Apps enabled (via the MCP_APPS feature flag or COPILOT_MCP_APPS=true environment override), the runtime adds the mcp-apps capability to the session, which causes it to advertise the extensions.io.modelcontextprotocol/ui extension to MCP servers (so they expose _meta.ui.resourceUri on tools) and to expose the session.rpc.mcp.apps.{listTools,callTool,readResource, setHostContext,getHostContext,diagnose} JSON-RPC methods.

      If the runtime gate is off, the opt-in is silently dropped server-side (the runtime logs a warning); the session is created normally but the MCP Apps surface is unavailable. Inspect SessionUiCapabilities.getMcpApps() on CopilotSession.getCapabilities() to detect this.

      SDK consumers MUST set this to true only when they have an iframe renderer that can display ui:// MCP App bundles. Setting it without a renderer will cause MCP servers to register UI-enabled tool variants the consumer cannot display.

      Parameters:
      enableMcpApps - true to opt into MCP Apps support
      Returns:
      this config instance for method chaining

    • getGitHubMcpToolConfig

      public GitHubMcpToolConfig getGitHubMcpToolConfig()
      Gets the configuration for the built-in GitHub MCP server.
      Returns:
      the GitHub MCP configuration, or null

    • setGitHubMcpToolConfig

      public SessionConfig setGitHubMcpToolConfig(GitHubMcpToolConfig githubMcpToolConfig)
      Sets the configuration for the built-in GitHub MCP server.
      Parameters:
      githubMcpToolConfig - the GitHub MCP configuration
      Returns:
      this config instance for method chaining

    • getOnExitPlanMode

      public ExitPlanModeHandler getOnExitPlanMode()
      Gets the exit-plan-mode request handler.
      Returns:
      the exit-plan-mode handler, or null
      Since:
      1.0.8

    • setOnExitPlanMode

      public SessionConfig setOnExitPlanMode(ExitPlanModeHandler onExitPlanMode)
      Sets a handler for exit-plan-mode requests from the server.

      When provided, the server will route exitPlanMode.request callbacks to this handler.

      Parameters:
      onExitPlanMode - the exit-plan-mode handler
      Returns:
      this config instance for method chaining
      Since:
      1.0.8
      See Also:

    • getOnAutoModeSwitch

      public AutoModeSwitchHandler getOnAutoModeSwitch()
      Gets the auto-mode-switch request handler.
      Returns:
      the auto-mode-switch handler, or null
      Since:
      1.0.8

    • setOnAutoModeSwitch

      public SessionConfig setOnAutoModeSwitch(AutoModeSwitchHandler onAutoModeSwitch)
      Sets a handler for auto-mode-switch requests from the server.

      When provided, the server will route autoModeSwitch.request callbacks to this handler.

      Parameters:
      onAutoModeSwitch - the auto-mode-switch handler
      Returns:
      this config instance for method chaining
      Since:
      1.0.8
      See Also:

    • getGitHubToken

      public String getGitHubToken()
      Gets the GitHub token for per-session authentication.
      Returns:
      the GitHub token, or null if not set
      Since:
      1.3.0

    • setGitHubToken

      public SessionConfig setGitHubToken(String gitHubToken)
      Sets the GitHub token for per-session authentication.

      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.

      Parameters:
      gitHubToken - the GitHub token for per-session authentication
      Returns:
      this config instance for method chaining
      Since:
      1.3.0

    • getGitHubTokenProvider

      public GitHubTokenProvider getGitHubTokenProvider()
      Gets the rotating GitHub token provider for this session.
      Returns:
      the provider, or null when a static token is used

    • setGitHubTokenProvider

      public SessionConfig setGitHubTokenProvider(GitHubTokenProvider gitHubTokenProvider)
      Sets the rotating GitHub token provider for this session.

      The provider receives only the effective host, optional assigned session ID, and acquisition reason. It must return a positive remaining lifetime in seconds when its callback completes. Production GitHub tokens typically last eight hours. This option is mutually exclusive with setGitHubToken(String).

      Parameters:
      gitHubTokenProvider - provider used for initial acquisition and refresh
      Returns:
      this config instance for method chaining

    • getRemoteSession

      public String getRemoteSession()
      Gets the per-session remote behavior control.

      Possible values:

      • "off" — local only, no remote export (default)
      • "export" — export session events to GitHub without enabling remote steering
      • "on" — export to GitHub AND enable remote steering
      Returns:
      the remote session mode, or null if not set
      Since:
      1.4.0

    • setRemoteSession

      public SessionConfig setRemoteSession(String remoteSession)
      Sets the per-session remote behavior control.

      Possible values:

      • "off" — local only, no remote export (default)
      • "export" — export session events to GitHub without enabling remote steering
      • "on" — export to GitHub AND enable remote steering
      Parameters:
      remoteSession - the remote session mode
      Returns:
      this config instance for method chaining
      Since:
      1.4.0

    • getCloud

      public CloudSessionOptions getCloud()
      Gets the cloud session options.

      When set, creates a remote session in the cloud instead of a local session. The optional repository is associated with the cloud session.

      Returns:
      the cloud session options, or null if not set
      Since:
      1.5.0

    • setCloud

      public SessionConfig setCloud(CloudSessionOptions cloud)
      Sets the cloud session options.

      When set, creates a remote session in the cloud instead of a local session. The optional repository is associated with the cloud session.

      Parameters:
      cloud - the cloud session options
      Returns:
      this config instance for method chaining
      Since:
      1.5.0

    • getExpAssignments

      public CopilotExpAssignmentResponse getExpAssignments()
      Gets the ExP assignment ("flight") data injected by a trusted integrator.
      Returns:
      the ExP assignment data, or null if not set

    • setExpAssignments

      public SessionConfig setExpAssignments(CopilotExpAssignmentResponse expAssignments)
      Sets ExP assignment ("flight") data injected by a trusted integrator.

      The value is in the same shape the Copilot CLI fetches from the experimentation service (CopilotExpAssignmentResponse). When provided, the runtime feeds it into the same feature-flag path as CLI-fetched assignments and stamps it onto telemetry and the CAPI request header. When absent, the session does not block on ExP. Intended for out-of-process integrators that fetch ExP data themselves; malformed payloads are dropped by the runtime (fail-open). Serialized on the wire as expAssignments.

      This is an internal/trusted-integrator option, not part of the broadly advertised public surface.

      Parameters:
      expAssignments - the ExP assignment data
      Returns:
      this config instance for method chaining

    • getFeatureFlags

      public Map<String,Boolean> getFeatureFlags()
      Gets host-resolved feature-flag values. @return the feature flags

    • setFeatureFlags

      public SessionConfig setFeatureFlags(Map<String,Boolean> featureFlags)
      Sets feature-flag values resolved by the host for this session.
      Parameters:
      featureFlags - the feature flags
      Returns:
      this config instance for method chaining

    • getEnableManagedSettings

      public Optional<Boolean> getEnableManagedSettings()
      Gets whether the runtime self-fetches enterprise managed settings at session bootstrap.
      Returns:
      an Optional containing true to opt into self-fetching managed settings, or Optional.empty() to use the default behavior

    • setEnableManagedSettings

      public SessionConfig setEnableManagedSettings(boolean enableManagedSettings)
      Opts the runtime into self-fetching enterprise managed settings (bypass-permissions policy) at session bootstrap.

      When true, the runtime self-fetches enterprise managed settings using the session's static gitHubToken or gitHubTokenProvider. Requires one of those credentials; if both are omitted, the runtime is expected to reject session creation (fail-closed). When unset, behaves exactly as before. Serialized on the wire as enableManagedSettings.

      Parameters:
      enableManagedSettings - true to opt into self-fetching managed settings
      Returns:
      this config instance for method chaining

    • getEnforceManagedModelDefaults

      public Optional<Boolean> getEnforceManagedModelDefaults()
      Gets whether locked managed model controls are enforced.
      Returns:
      the explicit choice, or empty to use the runtime default

    • setEnforceManagedModelDefaults

      public SessionConfig setEnforceManagedModelDefaults(boolean enforceManagedModelDefaults)
      Sets whether locked managed model controls are enforced for this session. Conflicting model changes are rejected; overridable defaults remain mutable.
      Parameters:
      enforceManagedModelDefaults - whether to enforce locked managed model controls
      Returns:
      this config instance for method chaining

    • getInteractiveUser

      public Optional<Boolean> getInteractiveUser()
      Gets whether this session is human-driven.
      Returns:
      an optional containing the declaration, or empty when unset

    • setInteractiveUser

      public SessionConfig setInteractiveUser(boolean interactiveUser)
      Declares that a human drives this session's conversation, enabling user-message analysis telemetry for user-authored messages. Automated messages remain excluded. Defaults to false for SDK sessions. Ignored for cloud sessions.
      Parameters:
      interactiveUser - true for interactive hosts such as editors or IDE chat panels
      Returns:
      this config instance for method chaining

    • getManagedSettings

      public ManagedSettings getManagedSettings()
      Gets host-injected managed settings for this session.
      Returns:
      the managed settings, or null when unset

    • setManagedSettings

      public SessionConfig setManagedSettings(ManagedSettings managedSettings)
      Supplies permissions-only managed settings at session startup. The runtime validates and composes this policy restrictively with self-fetched and device policy. Re-supply it on resume because it is not persisted.
      Parameters:
      managedSettings - the host-injected managed settings
      Returns:
      this config instance for method chaining

    • clone

      public SessionConfig clone()
      Creates a shallow clone of this SessionConfig instance.

      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.

      Returns:
      a clone of this config instance